ex_doc_makeup v0.1.1 ExDocMakeup

ExDoc-compliant markdown processor using Makeup for syntax highlighting.

This package is optimized to be used with ExDoc, and not alone by itself. It’s just Earmark customized to use Makeup as a syntax highlighter plus some functions to make it play well with ExDoc.

Link to this section Summary

Functions

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

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

Callback implementation for ExDoc.Markdown.assets/1.

Link to this function before_closing_body_tag(_)

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

Callback implementation for ExDoc.Markdown.before_closing_body_tag/1.

Link to this function before_closing_head_tag(_)

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

Callback implementation for ExDoc.Markdown.before_closing_head_tag/1.

Link to this function configure(options)

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.

Callback implementation for ExDoc.Markdown.configure/1.

Link to this function to_html(text, opts)

Converts markdown into HTML.

Callback implementation for ExDoc.Markdown.to_html/2.