ex_doc v0.19.3 ExDoc.Markdown.Cmark View Source
ExDoc extension for the Cmark Markdown parser.
Link to this section Summary
Functions
Assets specific to the markdown implementation
Check if the Cmark 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
Generate HTML output. Cmark takes no options
Link to this section Functions
assets(arg) View Source
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
Callback implementation for ExDoc.Markdown.assets/1
.
available?() View Source
Check if the Cmark Markdown parser module is available.
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
.
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
.
configure(_) View Source
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
.
to_html(text, opts) View Source
Generate HTML output. Cmark takes no options.