Hoe::Markdown

Hoe::Markdown is a Hoe plugin to help manage your project's markdown files. It's intended for gem maintainers, but the underlying library of markdown manipulation methods might be generally useful.

Hoe::Markdown::Standalone can be used without Hoe.

Installation

Add this line to your application's Gemfile:

gem 'hoe-markdown'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install hoe-markdown

Usage with Hoe

In your Rakefile:

Hoe::plugin :markdown

Rake tasks are exposed under the markdown namespace.

Choosing your markdown files correctly

Hoe makes some outdated assumptions about the location of your README and your changelog files, which you (as a maintainer) need to opt out of. Specifically, you probably have something like this in your Rakefile

Hoe.spec "projectname" do
  ...
  self.history_file = "CHANGELOG.md"
  self.readme_file = "README.md"
  ...
end

If you've got files named "CHANGELOG.md" and/or "README.md" then this plugin will do the right thing, and you won't need to specify this in your Rakefile.

Controlling what files are modified

By default, any .md file that Hoe knows about (through Manifest.txt or other attributes) will be included.

This can be overridden by setting the attribute named markdown_linkify_files which should be an array of file paths.

Rake Tasks

An idempotent rake task markdown:linkify is created which will iterate through each of the markdown files in your project, and create hyperlinks for:

• any github username [formatted like @username]
• github issue mention [formatted like #1234]
• github issue URI [which must match either the Hoe metadata URI for the bug tracker, or that same URI's equivalent pull request URI]

So, for example, this text:

# Changelog

## v1.0.0

Bugfix: Frobnicate the transmogrifier. #123
Thanks, @hobbes!

Feature: Finagle the sprocket. See https://github.com/cogswellcogs/sprocketkiller/issues/456

would be turned into:

# Changelog

## v1.0.0

Bugfix: Frobnicate the transmogrifier. [#123](https://github.com/cogswellcogs/sprocketkiller/issues/123)
Thanks, [@hobbes](https://github.com/hobbes)!

Feature: Finagle the sprocket. See [#456](https://github.com/cogswellcogs/sprocketkiller/issues/456)

Usage without Hoe

In your Rakefile:

require "hoe/markdown"
Hoe::Markdown::Standalone.new("gemname").define_markdown_tasks

This will attempt to read your gemspec from #{gemname}.gemspec, and then the same rake tasks described above are created and behave the same way. If you have additional files (beyond the files declared in the gemspec), you may pass them into this method:

require "hoe/markdown"
Hoe::Markdown::Standalone.new("gemname").define_markdown_tasks("CHANGELOG.md", "CONTRIBUTORS.md")

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/flavorjones/hoe-markdown. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License. See LICENSE.txt.

Code of Conduct

Everyone interacting in the Hoe::Markdown project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.