ex_doc v0.19.1 ExDoc.Markdown.Earmark View Source

ExDoc extension for the Earmark MarkDown parser.

Link to this section Summary

Functions

Assets specific to the markdown implementation

Check if the Earmark Markdown parser module is available

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

Earmark specific options

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.

Check if the Earmark Markdown parser module is available.

Link to this function before_closing_body_tag(arg) View Source

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(arg) View Source

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.

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.

Earmark specific options:

  • :gfm - boolean. Turns on Github Flavored Markdown extensions. True by default

  • :breaks - boolean. Only applicable if gfm is enabled. Makes all line breaks significant (so every line in the input is a new line in the output)

  • :smartypants - boolean. Turns on smartypants processing, so quotes become curly, two or three hyphens become en and em dashes, and so on. True by default

  • :plugins - map of strings to modules. Register custom plugins to be used with Earmark. See Plugins for details on how to write custom plugins.