Ornate is a tool for building multi-page HTML sites (like this one) from Markdown sources. The design goals are:
- Runs on the JVM; No installation required: Resolve the versioned dependencies in your build process for reproducible documentation builds with no external dependencies.
- Based on CommonMark, a standardized version of Markdown.
- Use well-established extensions: In particular, many developers are already familiar with Github-flavored Markdown.
- Graceful degradation: Some features require proprietary syntax extensions. They should degrade gracefully when processed with a pure CommonMark engine.
- Configuration based on Typesafe Config.
- Modular design: Themes, templates, highlighters, extensions - everything can be customized with Scala code.
- Clean, modern default theme using responsive design for a good user experience on all devices from mobile phones to desktop PCs.
- Update to Scala 2.12 and sbt 1.x
- Math notation in fenced code blocks
- Printer-friendly style for default theme
- Multi-threaded parsing and rendering
- Subscript and superscript extensions
- Smart quotes and smart punctuation
- Automatic ordering of extensions
- Configurable top and bottom navigation bars
- Foundation Icons anf Font Awesome support
- Easy customization of default theme (colors,
- Index support
- Automatic multi-version navigation
- Render included Markdown snippets
- External non-scaladoc links
- Bug fixes and minor features
- Math support via MathJax
- Mermaid diagrams support
- Scaladoc links support
- Snippet source links
- Target directory cleaning
- First published release
Page: A page comes from a single CommonMark source file. It has a source URI and a page URI in the
site:namespace. Themes can also create synthetic pages which are not associated with any source file.
Resource: A file which is copied verbatim to the generated site. Resources share the
site:namespace with pages. They can be provided as part of sources (together with pages) or be generated during processing.
TOC: The table of contents is built from a global configuration and the sections of all pages.
Site: The site consists of all pages and resources plus the computed TOC.
Extension: An extension can be a parser and/or renderer extension for commonmark-java or an Ornate extension for page processing. Extensions can be enabled separately for each page.
Theme: A theme is a class that renders the site in some way. The default themes generates HTML files and copies resources but themes are free to do whatever they want with the site.