ex_doc v0.20.0 ExDoc.Markdown behaviour View Source

Adapter behaviour and conveniences for converting Markdown to HTML.

ExDoc is compatible with any markdown processor that implements the functions defined in this module. The markdown processor can be changed via the :markdown_processor option in your mix.exs or via the :markdown_processor configuration in the :ex_doc configuration.

ExDoc supports the following Markdown parsers out of the box:

ExDoc uses Earmark by default.

Link to this section Summary

Functions

Gets the current markdown processor set globally.

Changes the markdown processor globally.

Converts the given markdown document to HTML.

Callbacks

Assets specific to the markdown implementation.

Literal content to be written to the file just before the closing body tag.

Literal content to be written to the file just before the closing head tag.

A function that accepts configuration options and configures the markdown processor.

Converts markdown into HTML.

Link to this section Functions

Link to this function

get_markdown_processor() View Source

Gets the current markdown processor set globally.

Link to this function

put_markdown_processor(processor) View Source

Changes the markdown processor globally.

Link to this function

to_html(text, opts \\ []) View Source

Converts the given markdown document to HTML.

Link to this section Callbacks

Assets specific to the markdown implementation.

This callback takes the documentation format (:html or :epub) as an argument and must return a list of pairs of the form {basename, content} where:

  • basename - relative path that will be written inside the doc/ directory.
  • content - is a binary with the full contents of the file that will be written to basename.

EPUB Documentation Gotchas

Generating HTML documentation is simple, and it works exacly as you would expect for a webpage. The EPUB file format, on the other hand, may cause some surprise.

Apparently, an EPUB file expects all assets to have a unique name when discarding the file extension.

This creates problems if you include, for example, the files custom.js and custom.css. Because the filename without the extension is equal (custom), you will get an unreadable EPUB. It's possible to go around this limitation by simply giving the files unique names:

  • custom.js becomes custom-js.js and
  • custom.css becomes custom-css.css

Example

def callback assets(_) do
  [{"dist/custom-css.css", custom_css_content()},
   {"dist/custom-js.js", custom_js_content()}]
end
Link to this callback

before_closing_body_tag(atom) View Source
before_closing_body_tag(atom()) :: String.t()

Literal content to be written to the file just before the closing body tag.

This callback takes the documentation format (:html or :epub) as an argument and returns a literal string. It is useful when the markdown processor needs to a include extra JavaScript.

Example

def callback before_closing_body_tag(_) do
  # Include the Javascript specified in the assets/1 callback
  ~S(<script src="dist/custom-js.js"></script>)
end
Link to this callback

before_closing_head_tag(atom) View Source
before_closing_head_tag(atom()) :: String.t()

Literal content to be written to the file just before the closing head tag.

This callback takes the documentation format (:html or :epub) as an argument and returns a literal string. It is useful when the markdown processor needs to a include extra CSS.

Example

def callback before_closing_head_tag(_) do
  # Include the CSS specified in the assets/1 callback
  ~S(<link rel="stylesheet" href="dist/custom-css.css"/>)
end
Link to this callback

configure(any) View Source
configure(any()) :: :ok

A function that accepts configuration options and configures the markdown processor.

It is run once when :ex_doc is loaded, and the return value is discarded. Modules that implement this behaviour will probably store the options somewhere so that they can be accessed when needed.

The format of the options as well as what the function does with them is completely up to the module that implements the behaviour.

Link to this callback

to_html(arg1, arg2) View Source
to_html(String.t(), Keyword.t()) :: String.t()

Converts markdown into HTML.