docmodel show menu hide menu

Markdown Support

docmodel uses marked for markdown processing. For the most part, a default marked configuration is used, but docmodel does add some small additional features. This page demonstrates elements of the most commonly used markdown syntaxes, but anything which is supported by marked should also be supported in docmodel. However, it is worth keeping in mind that a given theme might not provide styles for some elements.

Headings

To insert a heading (levels 1 to 6), start a line with the number of hash (#) symbols which correspond to the heading level you require, followed by a space, and then your heading:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
You should only use 1 H1 tag per page, as your page title. If using the default theme's TOCs, the first H1 on a page is always assumed to be the page's title and is removed from TOCs

Emphasis

To emphasize (em/italic) a piece of text, surround it with a single underscore (_) or asterisk (*) symbol on either side. To make a piece of text strong, surround it with two asterisk or underscore symbols on either side:

Some of this text will be **strong**, some will be _emphasized_, and some will be _**both**_.

Which will produce:

Some of this text will be strong, some will be emphasized, and some will be both .

Strike-through

To strike through a piece of test, surround it with 2 tilde (~) symbols on either side:

Some of this text will be ~~striked~~ struck through.

Which will produce: Some of this text will be striked struck through.

Tables

The syntax for creating a table is shown below. Please note that the characters you draw in each column of the text table do not have to be of equal width--the pipe characters are what separate columns:

A Table Heading   | Another Table Heading   | One more for fun
------------------|-------------------------|------------------
A first-row cell  | Another first-row cell  | Foo
A second-row cell | Another second-row cell | Bar!
It's the pipes that split columns | width doesn't matter | this is still 3 columns

This will produce:

A Table Heading Another Table Heading One more for fun
A first-row cell Another first-row cell Foo
A second-row cell Another second-row cell Bar!
It's the pipes that split columns width doesn't matter this is still 3 columns

You can align each column in a table left, right, or center by adding colon (:) symbols to the divider line (line of hyphens) under a table's heading row. To left align a column (the default), place a colon on the far left of a column's divider line. To right align a column, place a colon on the far right of a column's divider line. To center align a column, place a colon on the far right, and on the far left of a column's divider line. Each of these patterns is demonstrated below:

Right | Center | Left
-----:|:------:|:----
Test  | Test   | Test
Test  | Test   | Test

Which will result in:

Right Center Left
Test Test Test
Test Test Test

To insert a link, use a set of square brackets ([]) immediately followed by a set of normal brackets (()). Place your link text between the square brackets, and the URL you want to link to between the normal brackets:

Link to [docmodel](https://docmodel.com/)

Which will produce: Link to docmodel

To link to an internal document, use an at (@) symbol followed by the document's src file path (relative to your project's document directory):

Link to [a random document](@path/to/document.md)

To make your life a little easier, you can omit the link text for local files--docmodel will take it from your configuration file:

Link to [](@path/to/document.md)

You can learn more about internal links, including how you link to specific versions or languages for a document, in the section on Links and Local Files.

Images

The syntax for inserting an image looks very similar to that for inserting a link--a set of square and a set or round brackets. This time, these should be preceded by an exclamation mark (!). Alt text for the image should be placed between the square brackets, and the URL of the image you want to insert should appear between the round brackets. If you want to insert an image from your project's assets directory, use the format shown below (/assets/path/to/image.png -- note the leading /):

![Alt Text for the Image](/assets/images/logo.svg)

which will produce:

Alt Text for the Image

You can learn more about images in the section on Links and Local Files.

Lists

To turn a selection of lines into an unordered list, start each line with a single asterisk (*) symbol. For an ordered list, start each line with a number followed by a period. To nest lists, indent each addition list level by 4 spaces:

* This is an 
* unordered list


1. This is an 
2. ordered list


1. As has been
2. mentioned,
    1. you can indent
    2. list items
        * And you can mix the
        * types of nested lists
    3. Some more text here
3. To finish things off.


* You can also nest elements in a list by indenting them by 4 spaces:
    > This is a nested block quote.
  1. This is an
  2. ordered list
  1. As has been
  2. mentioned,
    1. you can indent
    2. list items
      • And you can mix the
      • types of nested lists
    3. Some more text here
  3. To finish things off.

Please take note of the 2 blank lines between distinct lists--these are required, and if not present one list will merge into the other.

Inline Code

To create an inline code block, surround your code segment with a single back tick (`) on either side:

This is a paragraph with `an inline code block`

The result of which will be:

This is a paragraph with an inline code block

Code Blocks

To insert a code block, surround your code segment with three back ticks (`) on either side. To specify the coding language for highlighting, add the language name after the first three back ticks:

  ```javascript
  setTimeout(() => {
    console.log('this is a JavaScript code block.');
  }, 1000);
  ````

The result of which will be:

setTimeout(() => {
  console.log('this is a JavaScript code block.');
}, 1000);

The docmodel default theme uses highlight.js for code highlighting. To see which languages are supported, how you can add support for additional languages, and how you can change the highlight styles, see the section on the Default Theme. In addition to back ticks, fences tildes (~~~) are also supported. If you need to nest one code block in another (like the one above, which shows the code block syntax in a highlighted code block), you can use a different number of back ticks for each level, or you can use the tilde syntax for one level, and the back ticks syntax for the other.

Block Quotes

To add a block quote, start a line with a greater than (>) symbol:

> This is a block quote
> > You can also nest block quotes

Which will produce:

This is a block quote

You can also nest block quotes

HTML

As you're working in your own trusted environment, docmodel does not sanitize HTML. You may place any arbitrary HTML in your markdown files and this will be preserved. Use this method to, as example, embed YouTube videos:

<iframe src="https://www.youtube.com/embed/eL1X8urHJmA" frameborder="0" allowfullscreen></iframe>

Which will produce:

Extras

In addition to marked's markdown support, docmodel also provides some additional document-level utilities.

To learn about internal links, including how you link internal documents, or to specific versions or languages for a document, see the section on Links and Local Files.

Theme Features

The default theme also provides a number of styling and content helpers, including the ability to include a document-level TOC. See the section on the Default Theme for more.

« PreviousNext »