Skip to content

docconvert.md

Latest commit

 

History

History
114 lines (81 loc) · 5.74 KB

docconvert.md

File metadata and controls

114 lines (81 loc) · 5.74 KB
Raw

docconvert ➡️

Convert Markdown documents to HTML

Syntax

docconvert(md) converts the Markdown document(s) md to HTML.

Multiple documents may also be specified using docconvert(md1,md2,...).

docconvert(...,"Theme",t) sets the theme t. Available themes are light, dark, and auto (responsive, default). For viewing as part of the MATLAB documentation, especially prior to R2025a, light mode works best. For viewing standalone, responsive mode works well.

docconvert(...,"Stylesheets",css) includes the stylesheet(s) css.

docconvert(...,"Scripts",js) includes the script(s) js. Scripts are included at the end of the body in the order specified to ensure that the HTML content is loaded and rendered before the scripts run. 🧪

docconvert(...,"Root",r) publishes to the root folder r, placing stylesheets and scripts in the subfolder resources. The root folder must be a common ancestor of the Markdown documents. If not specified, the root folder is the lowest common ancestor.

docconvert(...,"Interpreter",in) uses the text interpreter in. Available interpreters are "latex" (LaTeX markup) and "none" (literal text, default). Use single dollar signs $...$ to display equations inline, and double dollar signs $$...$$ to display equations on their own line, centered.

[html,res] = docconvert(...) returns the names of the HTML document(s) html and the resources folder res created.

Name Description Type Required
md➡️ Markdown document(s), as an absolute or relative path; wildcards are supported string(s) yes
t➡️ theme: light, dark, or auto; default is auto string(s)
css➡️ CSS stylesheet(s), as an absolute or relative path; wildcards are supported string(s)
js➡️ JavaScript script(s), as an absolute or relative path; wildcards are supported string(s) 🧪
r➡️ root folder, as an absolute or relative path; default is the lowest common ancestor of md string
in➡️ text interpreter: latex or none; default is none string
➡️html HTML document(s) created, as an absolute path string(s)
➡️res resources folder created, as an absolute path string

Examples

docconvert("mickey/pluto.md")

converts a single Markdown document mickey/pluto.md to HTML mickey/pluto.html. Note that this path is relative.

docconvert("C:\daisy\mickey\pluto.md")

also converts a single Markdown document, this time specified using an absolute path.

docconvert("mickey/*.md")

converts all Markdown documents in mickey to HTML.

docconvert("mickey/**/*.md")

converts all Markdown documents in mickey and its subfolders.

docconvert(["mickey/pluto.md" "mickey/donald.md"])

converts multiple Markdown documents to HTML.

docconvert("mickey/pluto.md","Stylesheets","huey/louie.css")

copies the stylesheet huey/louie.css to the resources folder and includes a <link> in the HTML <head>.

docconvert("mickey/pluto.md","Scripts","morty/ferdie.js")

copies the script morty/ferdie.js to the resources folder and includes a <script> in the HTML <body>. 🧪

docconvert("mickey/goofy/*.md","Root","mickey")

sets the root folder to mickey, rather than the lowest common ancestor mickey/goofy of the Markdown documents.

Details

Steps

The conversion consists of 7 steps:

  1. Read the Markdown document
  2. Convert Markdown to an HTML fragment using the GitHub Markdown API service
  3. Tidy up the HTML fragment in preparation for XML postprocessing
  4. Replace .md links in the fragment to .html -- Markdown links to Markdown, HTML links to HTML
  5. Build an HTML document around the HTML fragment
    • including default stylesheets, specified stylesheets, and specified scripts
    • using the first level-1 heading # Heading as the <html> <title>
  6. Copy the specified stylesheets and scripts to the resources folder in the root folder
  7. Write the document to an HTML document next to the original Markdown document

Styling

DocMaker seeks to provide pleasant style by default, but you can override the default styles by specifying your own stylesheets.

For example, to make level-2 headings ## Heading blue, create and specify a stylesheet with:

h2 {
  color: blue;
}

Since cascading stylesheets cascade, later styles override earlier styles.

This feature depends on reverse-engineering the HTML generated by the GitHub Markdown API service, although much of the behavior is obvious.

Postprocessing

Generated HTML may be postprocessed in the browser using JavaScript. Postprocessing code may be included by specifying the optional input Scripts. Scripts are included at the end of the body in the order specified to ensure that the HTML content is loaded and rendered before the scripts run.

This feature is experimental 🧪 and may be removed in a future version.

home 🏠 | convert ➡️ | run 🏃 | index 📜 | delete ♻️ | workspace 👷 | about 🐣 | ©️ MathWorks 2024-2026