FossMD

FossMD - Markdown documentation tool for Fossil SCM
Login

FossMD - Markdown documentation tool for Fossil SCM

Permalink

README for FossMD test suite

Description

This software has been designed to enhance the Fossil SCM documentation features:

The tool should be integrated with fossil seamlessly, so it may be used with any Fossil repository, including, but not limited to, the Fossil SCM itself.

Extensions

For syntax examples for Deployed Extensions, check:

https://github.com/commonmark/CommonMark/wiki/Deployed-Extensions

Examples:

DocBook-stylish layout

The current documentation for the Fossil SCM system uses a Wiki Index page, without any hierarchy.
It is somewhat hard to get the overview.
This tool aims to get an more readable overview of the documentation by imitating the DocBook documentation HTML layout.
Note that this software is not intended to emulate all available DocBook features.
This software just aims to simulate some of the DocBook's layout by creating "on-the-fly":

We just use DocBook's layout for table-of-contents (ToC) and navigation bars (navbars) to improve the user experience.
Creating the layout "on-the-fly" means that the Markdown file is not modified by any means, just the HTML output.

The DocBook-stylish layout is enabled by default, but can be disabled in the configuration.

Update: Another way to add the ToC could be to do as StackEdit:

[TOC]

The configuration option for ToC could thus be:

where manual would work the same as StackEdit.
UPDATE: Check man(1) tidy for exact syntax for different on/off options, and use that syntax.

Update: Support for Modular documentation, similar to DocBook's XInclude statement.
As a document grows in size, it is desireable to split it up into chapters. In DocBook, this is done by:

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml" /> 
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter1.xml" /> 
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chapter2.xml" /> 
    ...

In FossMD, this is done using Transclusion (see below for details):

    {{intro.md}}
    {{chapter1.md}}
    {{chapter2.md}}
    ...

MultiMarkdown-stylish enhancement

There are newer MarkDown formats which offer more features than John Gruber's original MarkDown flavor does, such as MultiMarkdown, which offer feautures such as:

Most (but not all) Markdown table formats supported by MultiMarkdown are also parsed correctly by Fossil.

Fenced Code Blocks may be used as an alternative to code blocks. Fenced code blocks are not supported by Fossil.
Fenced code blocks, used together with an Info String, is an easy way to, for example, syntax highlight source code, using only Markdown.
(Syntax highlighting, though not supported out-of-the-box in Fossil, may be achieved, as described here).
The example below is an example from CommonMark of how to higlight code using Fence Code Blocks.

    ```ruby
    def foo(x)
      return 3
    end
    ```

As mentioned before, File Transclusion permits for including other files into the Markdown document, and splitting one big document into several smaller:

{{intro.md}}
{{chapter1.md}}
{{chapter2.md}}

Each included file is parsed as any Markdown document. File Transclusion is not supported by Fossil.

File Transclusion is not limited to Markdown file types. Any file may be included.
This allows for including for example source code files into Markdown.
To avoid parsing the included source code as Markdown, is has to be placed inside a Fence Code Block.
Combining Fenced Code Blocks and File Transclusion is a very convenient way to highlight an entire source code file in a Markdown document:

    ```ruby
    {{foo.rb}}
    ```

How and if the syntax highlighting is done depends entirely on the configuration.
No information about how to parse Info Strings or how to syntax highlighting is hardcoded into FossMD, so if syntax highlighting is not configured (which basically means, including a JavaScript URL), the Fenced Code Block will be highlighted.
That is, there is no "fallback" or "by-default" highlighting included in the FossMD source code.

Syntax highlighting in a browser is normally made by JavaScript, detecting a CSS tag in the from-Markdown-generated HTML, such as <code class="language-ruby">, and parsing/modifying the text inside that tag.
As any file type may be included by File Transclusion, included files are not limited to source code.
Any JavaScript library for parsing/modifying text may be used to generate any kind of HTML/SVG output.
For example, a sequence diagram could be included in a Markdown document like this (as an SVG image):

    ```sequence
    Alice->Bob: Hello Bob, how are you?
    Note right of Bob: Bob thinks
    Bob-->Alice: I am good thanks!
    ```

(This syntax is already supported by the Marxico online Markdown editor, for example.)

The idea is to support any Info String, as long as it is configured by the user.
The advantage is that the user may add virtually any kind of contents to Markdown documents.
The disadvantage is that a document with custom Info Strings, for example sequence, is less "portable", as it may be difficult to read offline, if some of the content doesn't render properly.
That is, sending such a Markdown document to other users requires them to have a JavaScript library configured to view sequence diagrams, or they will just see the Fenced Code Block instead.
Exporting the document to for example PDF before distribution to a bigger audience is a recommended work-around.

Influences

Ideas for layout and enhancements have been picked from several projects, not only from DocBook and MultiMarkdown.
Read more about them in the Related section.

Background

Everyone (well, almost) hates to document their technical work.
If we found something being tricky in the documentation process, we will easily find an excuse to not create the document at all.
That is why it is so important that documentation tools must be as easy as possible to use.
Otherwise the documentation soon becomes outdated.

One of many DocBook features is that it creates "easy-browsable" HTML documents with table-of-contents and navigation bars created automatically.
A drawback for DocBook is the input source being XML, which makes it less-than-optimal when it comes to typing. Again, an excuse to avoid creating and/or updating documents. Another DocBook issue is the big toolchain and the big dependency list. DocBook is not a lightweight system.

Markdown documents, on the other hand, is lightweight, easy to write, but has no such built-in mechanism as creating table-of-contents and navigation bars.
A group of Markdown documents tends to be just a bunch of stand-alone documents, much like a Wiki, lacking a clear overview of the documentation.
This is true for any collection of Markdown documents, but what specially comes in mind is the documentation for the excellent Fossil SCM software.
This is best shown having a look at the documentation index page Fossil documentation index page, which is missing a hierarchical overview.

As we can see, the mentioned index page contains a list of Wiki pages, most of them not linked to each other.
Formatting the Wiki Index like a technical manual, similar to a DocBook index page, would create a clearer overview.
Here are two DocBook layout samples:
The DocBook manual itself and the BookDown home page (a PHP-based software for creating DocBook layout from Markdown)

It is quite common to include source code snippets in software documentation.
Using standard Markdown, this has to be done by Copy & Paste, and can be quite tedious to format correctly.
As mentioned before, features such as File Transclusion combined with automatic source highlighting makes this much easier.

Features

Also see Tickets.

Prioritary features

Secondary features

Design

Some characteristics are heavy influenced by the design of fossil:

The Perl version and the standalone C version should be functionally identical.
The HTML templates are software language independent, and can be used interchangeably between versions.
The "C-fossil" version should be able to deal with .wiki pages, even if contents is more restricted (no CSS, no Javascript) than for .md pages.

To render graphical content (in certain Fenced code blocks), the software should rely only on client-side (browser) JavaScript.
No graphic libraries should be included in any script/executable.

Perl version

To create the monolithic Perl script fossmd.pl, it is preferred to replace the original Markdown.pl with the "OO interfaced" CPAN module.
The following packages will all be included in the same monolithic script:

The Text::Markdown module converts Markdown to a HTML body, without any header.
fossmd.pl uses HTML::Template internally to create the table-of-contents, navigation bars, and page numbering.

TODO: A tool which concatenates all the CPAN modules, the CSS, HTML templates, JavaScript, and the code into a complete fossmd.pl.
This tool may then be used to "update" fossmd.pl to use the latest version of each CPAN module.

Perl license issues

There are no license issues with the Perl version, as the it will not integrate with Fossil SCM.

C version

The C version fossmd doesn't have the same "monolithic" issues as the Perl version, as we can create the monolithic executable fossmd at compile time.
The following "components" will be considered (very similar to the list of Perl packages)

One of the libs libdiscount %%% libsoldout software replaces Text::Markdown.
The libctemplate software (GPL) could replace HTML::Template for a standalone C executable, but cannot be used if integrating with Fossil.
Note that the use of templates is minimal, so maybe the "objcopy technique" http://kuu.se/fossil/objcopy.cgi/doc/tip/README.objcopy.md could be used for a simple template system.
The web server of the Fossil software replaces HTTP::Server::Simple. (Check the entry point void cmd_webserver(void) in src/main.c.)
The default HTML templates, the default CSS style sheets, and the JavaScript are declared as variables. (Again, either check Fossil to see how this is done, or use the "objcopy technique".)
OPTIONAL (requires C compiler): Save custom config in SQLite DB. Check Fossil to see how this is done.

C license issues

"C-Fossil" version

TODO: Check how the Markdown parsing is done in Fossil.
Create small test program using:

src/markdown.c
src/markdown_html.c

TODO: Check how the regex functions are implemented in Fossil.
Create regex test programs similar to https://kuu.se/fossil/cregex.cgi/raw?ci=trunk&filename=regperl.c using:

src/regexp.c

Emacs version

The Emacs version should be seen as tool, using fossmd as a backend.
We could follow three different path as base to generate MarkDown from within Emacs:

It would be nice use a similar design (a single backend script for HTML content generation) when generating HTML as-you-type.
Additional code is obviously required as-you-type, for example pushing contents contoniously to the browser, and to auto-scroll the browser window, for example.
Anyhow, the existing solutions use JavaScript not only for these functions, but also to generate the HTML contents.

Generating HTML as-you-type may cause a performance problem.
TODO: Check if the C standalone version is require as a backend, or the Perl version is fast enough.
TODO: Check if it is viable to use the Follsil version and fossil ui or fossil server as a backend.

Read BookDown source code

TODO: Read the PHP source code, Check how the DocBook table-of-contents, navigation bars, Automatic page numbering are created.

git clone https://github.com/bookdown/Bookdown.Bookdown.git

Especially navigation header and footer templates:
Bookdown.Bookdown/templates/navheader.php
Bookdown.Bookdown/templates/navfooter.php

Naming convention

The generated web pages are using the prefix 1.*, 1.1.*, 1.2.*, 1.1.1.*, 1.1.2.* etc. by default to indicate each page's level.
Only when using a configuration file, the prefix may be omitted.

How headers are translated into ToC (Table of Contents)

A common example

A less common example

A common example, multiple files

Configuration

There are basically three configuration cases:

  1. Don't use a configuration file. Details

    1. Split document by Markdown headers.
    2. Split by filenames.
    3. Split by directories.

  2. Use a configuration file. Details

    1. Split using nested Markdown lists in the configuration file.

  3. Use a configuration file, and customized using external HTML templates.
    The HTML header template may include links to external CSS style sheets and web fonts. Details

    1. Split using nested Markdown lists.
      Use external HTML templates to create an alternative table-of-contents and navigation bars.
      Use external CSS style sheets and web fonts to create a different look.

Case 1. No configuration

When using no configuration file, a document can be split by Markdown headers, by using separate Markdown files, and/or by using a directory tree.
These methods can be combined as described below.

Case 1.1. No configuration - Split by Markdown headers.

    # 1 `#` - This header starts a new page by default

    ## 2 `##` - This header also starts a new page by default

    ### 3 `###` - This header is included in the same page by default, but shows up as a separate chapter on the table-of-contents page, by default 


    ## 2 `######` - This header is included in the same page by default, but shows up as a separate chapter on the table-of-contents page, by default 

    ### 3 `######` - This header is included in the same page by default, but shows up as a separate chapter on the table-of-contents page, by default 

    #### 4 `######` - This header is included in the same page by default, but shows up as a separate chapter on the table-of-contents page, by default 

    ##### `######` - This header is included in the same page by default, but shows up as a separate chapter on the table-of-contents page, by default 

    ###### 6 `######` - This header is included in the same page by default, but shows up as a separate chapter on the table-of-contents page, by default

This is probably the most "natural" way to split sections in a Markdown document into HTML pages.

By default, the two top levels will be split into HTML pages.
This means that # and ## Markdown headers (corresponding to <h1> and <h2> HTML headers, respectively) will go into separate pages.
Any Markdown headers, level 1 to 6 (# to ######) will be reflected in the table-of-contents page by default.
Using this configuration method, there is no way to produce more than 6 levels in the table-of-contents page. With this method, it is possible to create an entire HTML output directory using one single Markdown file as input.

Case 1.2. No configuration - Split by filenames.

Multiple Markdown documents may be used as input, as a list of files.
The list of files is given from the command line, and will appear in the same order in the HTML output. The sections will be split in the same way as when using a single Markdown file.
If a directory is given as an argument, all Markdown files in that directory will be included by default. the sort order is alphabetical by default, so in that case it may be necessary to rename the filenames.
(Renaming files is not needed when using a configuration file.)
Optionally, the files can be ordered by modification date (ascending/descending).

An example of a directory ordered alphabetically:

    /my/markdown/dir
    |-- 1-introduction.md
    |-- 2-whatis.md
    |-- 3-getting-started.md
    |-- 4-prerequisites.md
    `-- 5-index.md

Case 1.3. No configuration - Split by directories.

This is very similar

An example of nested directories ordered alphabetically:

    /my/markdown/dir
    |-- 1-introduction
    |   |-- section1.md
    |   `-- section2.md
    |-- 2-whatis
    |   |-- section1.md
    |   `-- section2.md
    |-- 3-getting-started
    |   |-- section1.md
    |   `-- section2.md
    |-- 4-prerequisites
    |   |-- section1.md
    |   `-- section2.md
    `-- 5-index
        |-- section1.md
        `-- section2.md

Configuration file

%%%%%%% TODO: Resolve how to refer to relative links in document when files are split into chapters and into sections. TODO: How to specify this in ToC %%%%%%%

fossmd comes with an embedded, default configuration.
The configuration file syntax is standard Markdown.

To dump he configuration to STDOUT:

fossmd config dump

To save the configuration as a file:

fossmd [--global] config save [filename]

The configuration file name is .fossmd-config.md by default, saved in the current directory, considered the "project configuration".
If the --global option is used, the configuration file name is saved as .fossmd-config-global.md in the user's home directory.
fossmd gets its configuration like this:

  1. Read the embedded configuration.
  2. Read global configuration from .fossmd-config-global.md, which may override, partly or entirely, the embedded configuration.
  3. Read "project configuration" from .fossmd-config.md, which may override, partly or entirely, the global configuration.

To use a custom configuration file, run fossmd like this:

fossmd -c <config-file> [command]

Configuration summary

A summary of the configuration entries:

# include-files
# exclude-files
# include-subdirs
# exclude-subdirs
# sort-by
# sort-ascending
# toc
# icon-home
# icon-up
# icon-left
# icon-right

Configuration details

Lists (of files, for example), may be written on one single line separated by at one or more spaces, or may be written on separate lines.
The configuration file has the following entries, all optional:

# include-files

Description: List of Markdown filenames
Default value: * (include all *.md files)
Example:

file1.md
file2.md
file3.md
file4.md


# exclude-files

Description: List of Markdown filenames to be excluded
Default value: '' (empty string, that is, do not exclude any *.md files) 

# include-subdirs

Description: List of subdirectory where to search for additional Markdown files
Default value: * (include all files subdirectories)
Example:

1-introduction
2-whatis
3-getting-started
4-prerequisites
5-index


# exclude-subdirs

Description: List of subdirectory to be excluded from the search for additional Markdown files
Default value: '' (empty string, that is, do not exclude any subdirectory) 

# sort-by

Description: How to sort *md files
Options: date/name
Example: date 

# sort-ascending

Description: Flag for ascending/descending sort
Options: 1/true/TRUE/0/false/FALSE
Example: 1 

# toc

Example:

- Chapter 1
- Chapter 2
  - Chapter 2, section 1
  - Chapter 2, section 2
  - Chapter 2, section 3
  - Chapter 2, section 4
- Chapter 3
  - Chapter 3, section 1
  - Chapter 3, section 2
    - Chapter 3, section 2, subsection 1
    - Chapter 3, section 2, subsection 1
- Chapter 3, section 3
- Chapter 4

Output:

1. Chapter 1
2. Chapter 2
    2.1 Chapter 2, section 1
    2.2 Chapter 2, section 2
    2.3 Chapter 2, section 3
    2.4 Chapter 2, section 4
3. Chapter 3
  3.1 Chapter 3, section 1
  3.2 Chapter 3, section 2
    3.2.1 Chapter 3, section 2, subsection 1
      3.2.2 Chapter 3, section 2, subsection 1
    3.3 Chapter 3, section 3
4. Chapter 4



# icon-home

Path to image or Base64 coded data for Home icon.

# icon-up

Path to image or Base64 coded data for Up arrow icon.

# icon-left

Path to image or Base64 coded data for Left arrow icon.

# icon-right

Path to image or Base64 coded data for Right arrow icon.

Configuration notes

The entries include-files/exclude-files and include-subdirs/exclude-subdirs may be misconfigured.

One example is this configuration:

Coding Horror

BUG! BUG!

BUG!


    # include-files *

    # exclude-files *

This configuration tries to include and exclude all Markdown documents, which is obviously impossible.
In this case, the Include directives overrides the Exclude directives, and a warning about bad configuration appears.

Customize layout and style

HTML Templates

Dump default embedded HTML header and footer.

CSS Style Sheets

Dump default embedded CSS Style Sheets.

Web fonts

Dump default embedded web fonts (none - or musical by default, but with instructions how to use).

Related projects

CanvasJS Charts D3 abcjs - javascript for rendering abc music notation ABC notation Markx MathJax KaTeX MultiMarkdown Pandoc CommonMark PHP Markdown Extra Fossil SCM BookDown DocBook Markdown

Combining Markdown and DocBook lead to the existing BookDown software, which is similar to what we want to achieve with this software.
Anyway, BookDown is written in PHP, while we want to write this software in ANSI C.

The reason we want to use C is that one of the purposes with this software is to integrate it with Fossil, written in ANSI C.
Fossil comes with its own Markdown parser and renderer (for HTML) based on the original Markdown specification by John Gruber.
The original Markdown specification lacks support for tables, but that has been included in Fossil lately.

The syntax used for tables is the same as in the well specified PHP Markdown Extra project.
Even if Fossil's Markdown parser seems to fulfill our needs, we may have a look at the CommonMark project.
The project has recently made an effort to update the Markdown specification, and created parsers in different languages, among them, in C.

But even if we use Fossil's or CommonMark's C parser, there are some features that we have to look elsewhere for.
We want to be able to include external files into our documentation, such as program source code, and CSV files, to be listed as tables.
File inclusion is not part of the Markdown specification, but used as plugins in the Pandoc project.
We cannot use the Pandoc code directly (Pandoc is written in Haskell), but we will have a look at the syntax for how Pandoc handles included files.

Pandoc can be configured to parse only strict Markdown, or to accept additional features, such as tables, file inclusionm, math symbols, or musical scores.
This "feature level configuration" should be considered, even if in the end we may end up always enabling all features.
If we decide to be able to disable, for example, o block tables, math symbols or music scores, we also have to decide how to render such a block:

Similar features as offered by PHP Markdown Extra can also be found in MultiMarkdown.
The advantage is that MultiMarkdown is written in C, so that code may be reused in our project.
In recent releases, the math symbols feature seems to been have disabled by default.

Instead, to support math symbols, MathJax or KaTeX will be used.
The same $LaTeX$ syntax will be used as with Markx. Also true for KaTeX???

To support music scores in Markdown, the abc notation is the natural choice due to its simple text format.
The musical scores themselves will be rendered using abcjs.

If heavily using musical scores in documentation, VexFlow should at least be evaluated.
http://www.vexflow.com/
http://www.vexflow.com/vextab/
http://www.vexflow.com/vextab/playground/?foo

Advantages:

Support 'include file MIDI/ABC' as a complement to typing ABC direcly in Markdown, using abcMIDI:
http://abc.sourceforge.net/abcMIDI/

There doesn't seem to exist any standard syntax for abc notation embedded in Markdown.
Anyhow, using a similar syntax to $LaTeX$ (surrounded by $ or $$ signs) seems to be reasonable, like this:

CHARTS FROM CSV: CanvasJS Charts and/or D3

%%%

Markdown

Markdown

Advantages:

Disadvantages:

DocBook

DocBook

Advantages:

Disadvantages:

BookDown

BookDown

Advantages:

Disadvantages:

Fossil (from a point a view as a Markdown parser/renderer, not as a SCM)

Fossil SCM

Advantages:

Disadvantages:

PHP Markdown Extra

PHP Markdown Extra

Advantages:

Disadvantages:

PHP Markdown Extra: tables

Below follows the different allowed PHP Markdown Extra table syntaxes.
They all render correctly with Fossil (but not with John Gruber's original Markdown script):

Table 1: "Simple" table

syntax:

    First Header  | Second Header
    ------------- | -------------
    Content Cell  | Content Cell
    Content Cell  | Content Cell

rendered:

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

Table 2: Table with added leading and tailing pipes to each line

syntax:

    | First Header  | Second Header |
    | ------------- | ------------- |
    | Content Cell  | Content Cell  |
    | Content Cell  | Content Cell  |

rendered:

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

Table 3: Table with mixed alignment

syntax:

| Item      | Right-aligned value | Left-aligned value | Center-aligned value |
| --------- | -----:|:----- |:-----:|
| Computer  | $1600 | $1600 | $1600 |
| Phone     |   $12 |   $12 |   $12 |
| Pipe      |    $1 |    $1 |    $1 |

rendered:

Item Right-aligned value Left-aligned value Center-aligned value
Computer $1600 $1600 $1600
Phone $12 $12 $12
Pipe $1 $1 $1

Table 4: Table with formatted cells

syntax:

| Function name | Description                    |
| ------------- | ------------------------------ |
| `help()`      | Display the help window.       |
| `destroy()`   | **Destroy your computer!**     |

rendered:

Function name Description
help() Display the help window.
destroy() Destroy your computer!

Below follows an example MulltiMarkdown table which does not render correctly with Fossil:

Table 5: Table with caption and grouping

syntax:

[Table Caption]
|            |        Grouping           ||
| Left align | Right align | Center align |
|:-----------|------------:|:------------:|
| This       |        This |     This     |
| column     |      column |    column    |
| will       |        will |     will     |
| be         |          be |      be      |
| left       |       right |    center    |
| aligned    |     aligned |   aligned    |

rendered:

[Table Caption] | | Grouping || | Left align | Right align | Center align | |:-----------|------------:|:------------:| | This | This | This | | column | column | column | | will | will | will | | be | be | be | | left | right | center | | aligned | aligned | aligned |

MultiMarkdown

Image 1: Image with caption

Below follows an example MulltiMarkdown image which adds a caption, but behaves differently when using Fossil.
No caption text is created.
Instead, using Fossil, the caption text goes into the "alt" tag, and no "title" tag is created:

syntax:

![ABC](img/abc.png)

rendered:

ABC

Image 2: Image with b o l d e d caption

Below follows an example MulltiMarkdown image which adds a formatted (bold) caption, and image formatting, but behaves differently when using Fossil.
No caption text is created.
Instead, using Fossil, the caption text goes into the "alt" tag, and all text after the img URL goues into the "title" tag:

syntax:

![This is a **bolded** caption][ABC]

[ABC]: img/abc.png "ABC title" width="3in" height="2.4in"

rendered:

This is a **bolded** caption

PHP Markdown Extra: abbreviations

Markdown Extra adds supports for abbreviations (HTML tag <abbr>).
Below follows the PHP Markdown Extra abbreviations syntax.

According to https://talk.commonmark.org/t/abbreviations-and-acronyms/890

Abbreviations are supported by:

Abbreviations are NOT supported by:

Written in MarkDown

syntax:

Abbreviation definitions:

*[HTML]: Hyper Text Markup Language

*[W3C]:  World Wide Web Consortium

then, elsewhere in the document, write text such as:

The HTML specification
is maintained by the W3C.

rendered:

Abbreviation definitions:

*[HTML]: Hyper Text Markup Language

*[W3C]: World Wide Web Consortium

then, elsewhere in the document, write text such as:

The HTML specification is maintained by the W3C.

Note that this syntax does not render neither with Fossil (v. 2.1), nor with John Gruber's original Markdown script.

Written in HTML

The <abbr title="Hyper Text Markup Language">HTML</abbr> specification
is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.

The HTML specification is maintained by the W3C.

CommonMark

CommonMark

Advantages:

Disadvantages:

Pandoc

Pandoc

Advantages:

Disadvantages:

TODO %%%

MultiMarkdown

https://en.wikipedia.org/wiki/MultiMarkdown We should probably stick to MultiMarkdown, which seems to provide all kind of stuff we need!

Advantages:

Disadvantages:

cson_amalgamation.h

MultiMarkdown is released under both the GPL and MIT licenses. You may pick the license that best fits your needs.

Render graphics: Math symbols, Music scores, Charts, Flows and Sequences

Math symbols

Render Math symbols:
https://www.mathjax.org/
https://khan.github.io/KaTeX/

Markdown + Math:
http://markx.herokuapp.com/

Markx uses $LaTeX$ syntax in Markdown for Math symbols.
Just embed using $s or \\( and \\) for inline equations and $$s or \\[ and \\] for display mode:

- Inline mode: $E=mc^2$
- Display mode: $$\frac{df(x)}{dx}=\lim_{h \to 0}{\frac{f(y+h)-f(y)}{h}}$$

Music scores

Suggestions for how to embed ABC notation in Markdown

While math symbols may be used with either Inline mode and Display mode, only Display mode makes sense for music scores.
There are at least two reasons:

  1. From a layout view, it is hard to mix text with a tune on the same line.

  2. Using ABC notation, even the most minimal tune uses at least 3 lines of text:

    X:1
K:C
C2

Here is a list of formats from discussion about how to embed ABC notation in Markdown:
http://meta.music.stackexchange.com/questions/2507/how-could-abc-notation-be-embedded-in-our-posts-markdown
Note that these formats are only suggestions, not an established standard: 

$ABC$
M: 4/4
L: 1/8
K: Dmaj
|:D3 EFGFC|D2 A2 AF2E|D4 B2C2:|
$ABC$

$$
M: 4/4
L: 1/8
K: Dmaj
|:D3 EFGFC|D2 A2 AF2E|D4 B2C2:|
$$

$$X:1
K:C
C2 C2 C > D E2 | E > D E > F G4 |]
w:Row, row, row your boat, gent-ly down the stream.$$

Either:

    $$ABC$$
    X:1
    K:C
    C2 C2 C > D E2 | E > D E > F G4 |]
    w:Row, row, row your boat, gent-ly down the stream.
    $$ABC$$

Or:

    ```abc
    X:1
    K:C
    C2 C2 C > D E2 | E > D E > F G4 |]
    w:Row, row, row your boat, gent-ly down the stream.
    ```

The Marxico editor uses the second syntax for all kind of extensions, using triple backticks followed the extension name: https://marxi.co

    ```python
    PYTHON SOURCE CODE GOES HERE
    ```

    ```flow
    FLOW CHART GOES HERE
    ```

    ```sequence
    SEQUENCE DIAGRAM GOES HERE
    ```

So it is natural to use the same syntax for any other possible extension:

    ```abc
    ABC NOTATION GOES HERE
    ```

    ```cvs
    CVS DATA (TO BE DISPLAYED AS A HTML TABLE) GOES HERE
    ```

    ```chart
    CANVASJS CHARTS OR D3 DATA GOES HERE
    ```

    ```include
    FILE NAME GOES HERE
    ```

Note: The include statement uses the same syntax as described by the Pandoc "Include" package:
https://hackage.haskell.org/package/pandoc-include 

Format

The Code Blocks like the following will include every file in a new line.
The reference paths should be either absolute or relative to the folder where the pandoc command will be executed.

    ```include
    /absolute/file/path.md
    relative/to/the/command/root.md
    #do/not/include/this.md
    ```
Embed a single musical note in Markdown

Do't use ABC notation to just include "a musical note or two" in a text block, that would be overkill.
To include a note (without clef, lines or stave) in text:

Using a web font
Here is an example, using http://fontawesome.io/icon/music/:

    Here goes some text before the note <i class="fa fa-music" aria-hidden="true"></i>, and some text after.

Here are a few spezialized web fonts for music symbols:

http://www.fontspace.com/dvm-publications/metdemo/5592/charmap
http://www.fontspace.com/robert-allgeyer/musiqwik/5595/charmap
http://www.fontspace.com/david-rakowski/lassus/3057/charmap

Using Unicode
Every editor has its way to insert Unicode.
Normally, copy paste should work fine, as with any other character.

In Emacs, put the cursor over the note:

    ♫  ♪

    M-x describe-char

This gives us the info:

    code point in charset: 0x266B
    to input: type "C-x 8 RET HEX-CODEPOINT" or "C-x 8 RET NAME"

Example:

    C-x 8<ENTER>
    Insert character (Unicode name or hex): 266A
    ♪

The 2669 - 266F Unicode range renders fine in my browser, while the G clef sign (Unicode 1D11E) does not:
♩ ♪ ♫ ♬ ♭ ♮ ♯ 𝄞

https://en.wikibooks.org/wiki/Unicode/List_of_useful_symbols#Music http://xahlee.info/comp/unicode_music_symbols.html

Include MIDI files, convert to ABC, render with abcjs

TBD

JavaScript for rendering ABC music notation:

https://abcjs.net/

CanvasJS Charts

CanvasJS Charts

Advantages:

Disadvantages:

D3

D3 - Data-Driven Documents

Advantages:

Disadvantages:

var s = "JavaScript syntax highlighting";
alert(s);

Flows and Sequences

Alternative 1: Mermaid
Alternative 2: js-sequence-diagrams
Syntax examples: stackedit

Links

This page:
http://kuu.se/fossil/fossmd.cgi
Markdown
http://daringfireball.net/projects/markdown/syntax
http://daringfireball.net/projects/markdown/dingus
DocBook
http://docbook.org
BookDown
http://bookdown.io
Discount - C implementation of Markdown
http://www.pell.portland.or.us/~orc/Code/discount/
HTML::Template - Perl/CPAN implementation
http://search.cpan.org/~wonko/HTML-Template-2.95/
libctemplate - a C implementation of HTML::Template
http://libctemplate.sourceforge.net/
PHP Markdown Extra:
https://michelf.ca/projects/php-markdown/extra

CSS tree menu

http://www.thecssninja.com/css/css-tree-menu
http://cssdeck.com/labs/pure-css-tree-menu-framework http://codepen.io/bisserof/pen/fdtBm/ (JavaScript)
http://www.bypeople.com/css-treeview/

JavaScript Syntax Highlight

https://highlightjs.org/

JavaScript search

JSSINDEX
http://jssindex.sourceforge.net/

Responsive CSS

https://necolas.github.io/normalize.css http://mincss.com/
http://getskeleton.com/
http://purecss.io/
http://getbootstrap.com/

PDF

libHaru - C library for creating PDF documents
https://github.com/libharu/libharu/wiki
PDF::Haru - PDF Creator depending on libHaru
http://search.cpan.org/~butilw/PDF-Haru-1.00/lib/PDF/Haru.pm
PDF::Create - Pure Perl PDF Creator
http://search.cpan.org/~manwar/PDF-Create-1.34/lib/PDF/Create.pm

PDF - JavaScript based

https://parall.ax/products/jspdf
http://pdfmake.org
http://pdfkit.org/

ToC generators

https://github.com/ardumont/markdown-toc (elisp)
https://github.com/thlorenz/doctoc (node.js)

PDF - 6 HASHES TEST

6 HASHES HERE

####### PDF - 7 HASHES TEST 7 HASHES HERE