# Hoe::Markdown

Hoe::Markdown is a [Hoe](https://www.zenspider.com/projects/hoe.html) 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.


## Installation

Add this line to your application's Gemfile:

```ruby
gem 'hoe-markdown'
```

And then execute:

    $ bundle install

Or install it yourself as:

    $ gem install hoe-markdown


## Usage

In your Rakefile:

``` ruby
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:

```markdown
# 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:

```markdown
# 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)
```

## 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](https://github.com/flavorjones/hoe-markdown/blob/master/CODE_OF_CONDUCT.md).


## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). See [LICENSE.txt](https://github.com/flavorjones/hoe-markdown/blob/master/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](https://github.com/flavorjones/hoe-markdown/blob/master/CODE_OF_CONDUCT.md).