From 437254976c1a679c4a9b6f1a7648de5bc72866db Mon Sep 17 00:00:00 2001 From: Tom von Schwerdtner Date: Tue, 29 Dec 2015 12:40:10 -0500 Subject: [PATCH 1/2] Add Cmark to list of markdown processors Also add mention of cmark to README --- README.md | 6 ++++-- lib/ex_doc/markdown.ex | 10 ++++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e0c4a3adc..f646b65f9 100644 --- a/README.md +++ b/README.md @@ -65,15 +65,17 @@ For example, here are some acceptable values: ## Changing the Markdown tool -In the examples above, we have used [Earmark](http://github.com/pragdave/earmark) to convert Markdown to HTML. If you prefer, you can also use pandoc or hoedown (in C): +In the examples above, we have used [Earmark](http://github.com/pragdave/earmark) to convert Markdown to HTML. If you prefer, you can also use pandoc, hoedown (in C), or cmark (in C): * Install [pandoc](http://johnmacfarlane.net/pandoc/) - which is available in multiple package managers and provides installers for different operating systems. Pandoc must be installed just once and it will be used for all projects; * To use hoedown - add http://github.com/devinus/markdown as a dependency to your project as: `{:markdown, github: "devinus/markdown"}` + * To use cmark - add `cmark.ex` as a dependency to your project as: `{:cmark, "~> 0.5"}` + Then add the entry: - config :ex_doc, :markdown_processor, ExDoc.Markdown.Pandoc # or ExDoc.Markdown.Hoedown + config :ex_doc, :markdown_processor, ExDoc.Markdown.Pandoc # or ExDoc.Markdown.Hoedown, or ExDoc.Markdown.Cmark to your `config/config.exs` file. diff --git a/lib/ex_doc/markdown.ex b/lib/ex_doc/markdown.ex index 83cb43bb0..377d1e760 100644 --- a/lib/ex_doc/markdown.ex +++ b/lib/ex_doc/markdown.ex @@ -7,20 +7,23 @@ defmodule ExDoc.Markdown do * [Hoedown][] * [Earmark][] * [Pandoc][] + * [Cmark][] If you don't specify a parser in `config/config.exs`. ExDoc will try to - find one of the Markdown parser from the list in top down fashion. Otherwise, + find one of the Markdown parser from the list in top down fashion. Otherwise, ExDoc will raise an exception. [Pandoc]: http://johnmacfarlane.net/pandoc/ [Hoedown]: https://github.com/hoedown/hoedown [Earmark]: http://github.com/pragdave/earmark + [Cmark]: https://github.com/asaaki/cmark.ex """ @markdown_processors [ ExDoc.Markdown.Hoedown, ExDoc.Markdown.Earmark, - ExDoc.Markdown.Pandoc + ExDoc.Markdown.Pandoc, + ExDoc.Markdown.Cmark ] @markdown_processor_key :markdown_processor @@ -75,6 +78,9 @@ defmodule ExDoc.Markdown do * Add {:markdown, github: "devinus/markdown"} to your mix.exs deps to use a C-based markdown processor + * Add {:cmark, ">= 0.5"} to your mix.exs deps + to use another C-based markdown processor + * Ensure pandoc (http://johnmacfarlane.net/pandoc) is available on your system to use it as an external tool """ From 1606854e13d54f088eb19c4741d3004a89c3f445 Mon Sep 17 00:00:00 2001 From: Tom von Schwerdtner Date: Tue, 29 Dec 2015 13:09:05 -0500 Subject: [PATCH 2/2] Reformat alternate parser instructions Also juggle some link definitions for the sake of (somewhat subjective) text-based readability. --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 59 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index f646b65f9..cd3d082db 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ # ExDoc -[![Build Status](https://secure.travis-ci.org/elixir-lang/ex_doc.svg?branch=master "Build Status")](http://travis-ci.org/elixir-lang/ex_doc) [![Coverage Status](https://coveralls.io/repos/elixir-lang/ex_doc/badge.svg?branch=master&service=github)](https://coveralls.io/github/elixir-lang/ex_doc?branch=master) +[![Build Status](https://secure.travis-ci.org/elixir-lang/ex_doc.svg?branch=master "Build Status")][build-status] +[![Coverage Status](https://coveralls.io/repos/elixir-lang/ex_doc/badge.svg?branch=master&service=github)][coverage-status] -ExDoc is a tool to generate documentation for your Elixir projects. In case you are looking for documentation for Elixir itself, [check out Elixir's website](http://elixir-lang.org/). +ExDoc is a tool to generate documentation for your Elixir projects. In case you are looking for documentation for Elixir itself, [check out Elixir's website][elixir-lang]. ## Using ExDoc with Mix @@ -41,19 +42,25 @@ To see all options available when generating docs, run `mix help docs`. You ma You can ExDoc via the command line as follows: 1. First clone and compile it: - - git clone https://github.com/elixir-lang/ex_doc.git - cd ex_doc - mix do deps.get, compile +2. + ```console + $ git clone https://github.com/elixir-lang/ex_doc.git + $ cd ex_doc + $ mix do deps.get, compile + ``` 2. Then you are ready to use it in your projects. First move into your project directory and ensure it is compiled: - cd PATH_TO_YOUR_PROJECT - mix compile + ```console + $ cd PATH_TO_YOUR_PROJECT + $ mix compile + ``` 3. Next invoke the ex_doc executable from your project: - PATH_TO_YOUR_EXDOC/bin/ex_doc "PROJECT_NAME" "PROJECT_VERSION" path/to/project/ebin -m "PROJECT_MODULE" -u "https://github.com/GITHUB_USER/GITHUB_REPO" -l path/to/logo.png + ```console + $ PATH_TO_YOUR_EXDOC/bin/ex_doc "PROJECT_NAME" "PROJECT_VERSION" path/to/project/ebin -m "PROJECT_MODULE" -u "https://github.com/GITHUB_USER/GITHUB_REPO" -l path/to/logo.png + ``` For example, here are some acceptable values: @@ -65,22 +72,58 @@ For example, here are some acceptable values: ## Changing the Markdown tool -In the examples above, we have used [Earmark](http://github.com/pragdave/earmark) to convert Markdown to HTML. If you prefer, you can also use pandoc, hoedown (in C), or cmark (in C): +In the examples above, we have used [Earmark][] to convert Markdown to HTML. If you prefer, you can also use pandoc, hoedown (in C), or cmark (in C). + +### Pandoc + +Install [pandoc][] using whichever means is appropriate for your system. Odds are good it is available via whatever package manager you have available to you. - * Install [pandoc](http://johnmacfarlane.net/pandoc/) - which is available in multiple package managers and provides installers for different operating systems. Pandoc must be installed just once and it will be used for all projects; +Update your project config to use pandoc: - * To use hoedown - add http://github.com/devinus/markdown as a dependency to your project as: `{:markdown, github: "devinus/markdown"}` +```elixir +config :ex_doc, :markdown_processor, ExDoc.Markdown.Pandoc +``` - * To use cmark - add `cmark.ex` as a dependency to your project as: `{:cmark, "~> 0.5"}` +### Hoedown -Then add the entry: +Hoedown is a standards compliant Markdown parser written in C. To use hoedown, add the elixir NIF wrapper [markdown][devinus/markdown] as a dependency to your project: - config :ex_doc, :markdown_processor, ExDoc.Markdown.Pandoc # or ExDoc.Markdown.Hoedown, or ExDoc.Markdown.Cmark +```elixir +{:markdown, github: "devinus/markdown"} +``` + +Update your project config to use hoedown: + +```elixir +config :ex_doc, :markdown_processor, ExDoc.Markdown.Hoedown +``` -to your `config/config.exs` file. +### Cmark + +[Cmark][cmark] is a CommonMark parser written in C. To use cmark add the elixir NIF wrapper [cmark.ex][cmark.ex] as a dependency to your project: + +```elixir +{:markdown, github: "devinus/markdown"} +``` + +Update your project config to use Cmark: + +```elixir +config :ex_doc, :markdown_processor, ExDoc.Markdown.Cmark +``` # License ExDoc source code is released under Apache 2 License. The generated contents, however, are under different licenses based on projects used to help render html, including css, js and other assets. Check the [LICENSE](LICENSE) file for more information. + + +[coverage-status]: https://coveralls.io/github/elixir-lang/ex_doc?branch=master +[build-status]: http://travis-ci.org/elixir-lang/ex_doc +[earmark]: http://github.com/pragdave/earmark +[elixir-lang]: http://elixir-lang.org/ +[pandoc]: http://johnmacfarlane.net/pandoc/ +[cmark]: https://github.com/jgm/cmark +[cmark.ex]: https://github.com/asaaki/cmark.ex +[devinus/markdown]: http://github.com/devinus/markdown