ex_doc v0.21.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
Gets the current markdown processor set globally.
Changes the markdown processor globally.
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 thedoc/
directory.content
- is a binary with the full contents of the file that will be written tobasename
.
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
becomescustom-js.js
andcustom.css
becomescustom-css.css
Example
def callback assets(_) do
[{"dist/custom-css.css", custom_css_content()},
{"dist/custom-js.js", custom_js_content()}]
end
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
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
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.
Converts markdown into HTML.