Warning
NMD syntax is working in progress yet, you can contribute following contribution guidelines!
- Structure
- NMD Syntax
- Heading (Title of a chapter)
- Inline modifier
- Paragraph modifier
There are several type of ways to write NMD.
The structure hierarchy is the following:
- Dossier: structured project
- Document: single NMD file having
.nmd
extension - Chapter: actual NMD text, it is identified by the heading and it has some paragraph
- Paragraph: actual NMD text, it is the text block in a chapter. Each paragraph is separated by each other by two new lines (
\n\n
)
A dossier is a structured project having one or more NMD documents.
It allows to manage a set of related NMD documents and their assets.
Asset is a resource used in a document, e.g. an image, or a custom style.
A dossier allows to write the content in different NMD files and than union them in a single output.
The actual structure of a dossier is the following:
assets/
images/
documents/
styles/
- ...
nmd.yml
ornmd.json
called dossier configuration- set of NMD document (having
.nmd
extension)
The images/
directory contains... images! Such as documents
which contains documents and styles/
which contains custom style for dossier.
The custom style must be written in CSS. The CSS classes are specified in each following modifier section.
The dossier configuration is a YAML or JSON file which contains configuration parameters for the dossier.
Considering YAML version, it may have the following content:
name: New Dossier
toc:
include_in_output: false
page_numbers: false
plain: false
maximum_heading_level: 4
documents:
- ./welcome.nmd
style:
theme: Light
styles: []
list_bullets_configuration: []
references: {}
bibliography:
title: Bibliography
records: {}
include_in_output: false
compilation:
embed_local_image: true
embed_remote_image: true
compress_embed_image: true
strict_image_src_check: true
parallelization: true
use_remote_addons: false
name
is the name of dossier.
include_in_output
if it must be printed
page_numbers
: if it must be had page numbers
tabulated
if it must contains tabulations
maximum_heading_level
maximum heading level which must be printed
To customize table of contents there are some classes: toc
, toc-title
, toc-body
, toc-item
, toc-item-bullet
, toc-item-content
, toc-item-indentation
documents
is a list where are specified the order of the documents in the final output.
style
section has the style configuration.
theme
specified the theme used to create output. It can be:
Light
(default)Dark
Vintage
is work in progress now
styles
refers to CSS files. They can be URLs or local files (if only file name is used, it is inferred assets/styles/
as prefix)
list_bullets_configuration
is described in list section
references
allows to specify dossier variables.
Each bibliography record has:
title
(mandatory)year
authors
description
url
Style classes: bibliography
, bibliography-title
, bibliography-body
, bibliography-item
, bibliography-item-title
, bibliography-item-authors
, bibliography-item-year
, bibliography-item-url
For example:
bibliography:
title: Bibliography
records:
bib1:
title: "bib1"
bib2:
title: "bib1"
authors:
- A1
- A2
- A3
year: 2024
bib3:
title: "bib1"
description: "bib3 description"
include_in_output: true
In compilation
section you can specified the default values to use during compilation.
embed_local_image
(boolean): local images (specified by local path) are inserted in the output without reference, but embeddedembed_remote_image
(boolean): remote images (specified by remote path, e.g. URL) are inserted in the output without reference, but embeddedcompress_embed_image
(boolean): compress embedded imagesstrict_image_src_check
(boolean): apply a strict check to image sourcesparallelization
(boolean): iftrue
parallelize execution of compilationuse_remote_addons
(boolean): iftrue
use CDN instead of local CSS/Javascript to include third part library
NMD syntax is based on CommonMark, but add new concepts and modifiers.
A modifier is a special combination of symbols which allows to modify the text style.
In the next section there are all modifiers of NMD.
Style class: heading-#
(where #
is the heading number, e.g. heading-3
)
Create headings using #
(up to 6 levels). #
must be separated from text using a blank space
.
# Heading 1
## Heading 2
...
###### Heading 6
It's possible to use this alternative format:
#1 Heading 1
#2 Heading 2
...
#6 Heading 6
It's possible to use this alternative format to refer previous heading level:
-
#-
$= \text{last heading level} - 1$ -
#+
$= \text{last heading level} + 1$ -
#=
$= \text{last heading level}$
For example:
#1 Heading 1
#+ Heading 2
#+ Heading 3
#- Heading 2
#= Heading 2
@key value1;value2
id
author
date
of creationintent
style
(inline style, e.g.color:red
)styleclass
(style class, e.g.bold-txt
)
TODO
You can prevent text modification using escape, i.e. \
:
\*
\_
...
Metadata are a set of data which gives information about document, project and so on.
The syntax is:
TBD
Reference is a... reference! You can use a fictitious name as a classic variable in the programming languages.
References must be set in dossier configuration (nmd.json
or nmd.yml
).
The syntax is below.
&reference&
Style class: bold
**Bold**
or
__Bold__
Style class: italic
_Italic_
or
*Italic*
Style class: strikethrough
~~Strikethrough text~~
Style class: underlined
++Underlined text++
Style class: checkbox
, checkbox-unchecked
, checkbox-checked
[x] or [x]
[] or [ ]
Style class: abridged-embedded-style
Color can be written in hexadecimal if you use #rrggbb
convention or you can use their names.
You can modify text color, text background and its font using this modifier:
[Custom colored text]#id{textColor;backgroundColor;fontName}
You can omit id
.
You can omit font and background color if you want only modify text color.
[Only text color]{#rrggbb}
You can insert only background color or only text font using this convention:
[Only background]{;#rrggbb}
[Only font]{;;fontName}
Style class: highlight
You can use also ==Highlight text==
to mark text. This uses the default highlight style.
Style class: embedded-style
[Custom text style]{{style}}
style
is literally the css-like style to apply.
Style class: identifier
You can mark with an identifier a piece of text using:
[Text]#the-id
You can combine identifier modifier with embedded style:
[Text]#the-id{textColor;backgroundColor;fontName}
[Text]#the-id{{style}}
Two ways to add emoji:
- Copy and paste an emoji
- Using
:emojiCode:
, for example 🐫
1^st^
This modifier can be placed attached on other text.
For example, if you want to write "water" in a more scientific way:
H~2~O
Pay attention, those are two single quote
This modifier can be placed attached on other text.
Style class: link
[Link](http://https://github.com/nricciardi/nmd.com)
Style class: inline-code
`inline code`
Style class: inline-math
$inline math$
// this is a comment
Style class: greek
%a%
%b%
%athb%
...
HashMap::from([
("a", r"alpha"),
("b", r"beta"),
("g", r"gamma"),
("d", r"delta"),
("e", r"epsilon"),
("z", r"zeta"),
("n", r"eta"),
("th", r"theta"),
("i", r"iota"),
("k", r"kappa"),
("l", r"lambda"),
("m", r"mu"),
("nu", r"nu"),
("x", r"xi"),
("o", r"omicron"),
("p", r"pi"),
("r", r"rho"),
("s", r"sigma"),
("t", r"tau"),
("u", r"upsilon"),
("phi", r"phi"),
("chi", r"chi"),
("psi", r"psi"),
("w", r"omega"),
("A", r"Alpha"),
("B", r"Beta"),
("G", r"Gamma"),
("D", r"Delta"),
("E", r"Epsilon"),
("Z", r"Zeta"),
("N", r"Eta"),
("Th", r"Theta"),
("I", r"Iota"),
("K", r"Kappa"),
("L", r"Lambda"),
("M", r"Mu"),
("Nu", r"Nu"),
("X", r"Xi"),
("O", r"Omicron"),
("P", r"Pi"),
("R", r"Rho"),
("S", r"Sigma"),
("T", r"Tau"),
("U", r"Upsilon"),
("Phi", r"Phi"),
("Chi", r"Chi"),
("Psi", r"Psi"),
("W", r"Omega"),
])
Bookmarks are label which can be inserted in text body to mark a paragraph or a piece of paragraph.
Style class: abridged-bookmark
, abridged-bookmark-title
@[bookmark description]
@[bookmark description]#the-id
Description can be multi-lines.
Style class: bookmark
, bookmark-title
, bookmark-description
@[bookmark title](bookmark description)
@[bookmark title]#the-id(bookmark description)
Style class: todo
, todo-title
, todo-description
, abridged-todo
, multiline-todo
Todo is a special tag to insert... TODOs
@[TODO](description)
@[todo](description)
...or only as first characters of the line:
TODO: description
todo: description
Multiline todo:
TODO:
this is a multiline todo
:TODO
Style class: cite
some text^[bibliography-key]
Style class: embedded-paragraph-style
, abridged-embedded-paragraph-style
[[Custom text
style]]{{style}}
style
is literally the css-like style to apply.
[[Custom text
style]]{}
Style class: figure
, image
, image-caption
![Image](http://url/a.png)
![Image]#id(http://url/a.png)
![Image]#id(http://url/a.png){maring:0;width:50vw}
Style class: figure
, image
, abridged-image
![(http://url/a.png)]
![(http://url/a.png)]#id
![(http://url/a.png)]#id{maring:0;width:50vw}
Style class: figure
, image
, image-caption
, abridged-image
, images-container
, image-container
!!:space-between:[[
:center:![(wikipedia-logo.png)]#image-7{width:70%}
![Wikipedia](./assets/images/wikipedia-logo.png){width:45%;margin:0;}
]]
Style class: page-break
### or more #
Style class: line-break
, line-break-dash
, line-break-star
, line-break-plus
To apply a line break use ---
(or more than 3 -
) or ***
(or more than 3 *
) or +++
(or more than 3 +
) in a new blank line.
Style class: list
, list-item
, list-item-indentation
, list-item-bullet
, list-item-content
Each list must have 2 or more items.
Different types of list are supported in NMD, below the list with modifier
-
default style bullet*
full dot bullet+
empty dot bullet->
arrow bullet--
dash bullet|
to use more than one line in an item content-[] or -[ ] or - [] or - [ ]
todo bullet1. or 1) or a. or a) or I. or I)
ordered bullet (numerical, alphabetical, romans numbers)&unicode;
UNICODE bullet
Using tabs
or
(3 spaces) you can create different list levels.
Style of first and second bullet types can be managed using the configuration file.
Actually, the behavior of bullets can be modified using dossier configuration. In particular, using list_bullets_configuration
.
For each record, you must specified 4 fields:
from
(string): NMD bulletto
(string): output bullet (:checkbox:
or:checkbox-checked:
to show checkbox bullets)indentation_level
(number)strict_indentation
(boolean): iffalse
the actual rule use>=
instead of==
to check indentation
The rules are checked in order.
Following an example:
list_bullets_configuration:
- from: '|'
to: '‍'
indentation_level: 0
strict_indentation: false
- from: '-'
to: '•'
indentation_level: 0
strict_indentation: true
- from: '-'
to: '◦'
indentation_level: 1
strict_indentation: true
- from: '-'
to: '–'
indentation_level: 2
strict_indentation: false
- from: '*'
to: '•'
indentation_level: 0
strict_indentation: false
- from: +
to: '◦'
indentation_level: 0
strict_indentation: false
Style class: code-block
Code blocks use ``` as paragraph modifier.
It's possible to specify the language used in code block, as in CommonMark, writing language name after first three quotes.
NMD uses PrimJS to render code blocks. So, the supported languages (tag in parenthesis) are the same of that library:
- Python (python)
- Java (java)
- Javascript (javascript)
- PHP (php)
- HTML (html)
- CSS (css)
- Typescript (typescript)
- Kotlin (kotlin)
- ...
/*
multi
line
comment
*/
Style class: focus-block
, focus-block-type
, focus-block-title
, focus-block-type-title
, focus-block-description
, focus-block-type-description
(replace type
)
Focus blocks allow to insert text in particular paragraph in which the text is highlighted.
There are many types of focus block:
- quote
- note
- tip
- important
- warning
- caution
The syntax is below.
::: warning
Watch out!!!
:::
Style class: focus-quote-block
, focus-quote-block-type
, focus-quote-block-title
, focus-quote-block-type-title
, focus-quote-block-description
, focus-quote-block-type-description
(replace type
)
> [!note]
> note...
Only for
[!type]
pattern you can writetype
in uppercase (TYPE
).
Style class: math-block
Math block is a particular paragraph used to print mathematical formulas and more.
The paragraph modifier for math block is double $, i.e. $$
to open and close blocks.
NMD uses Katex to render math blocks.
In NMD each paragraph can be decorated with a set of paragraph decorators, i.e. metadata, in-line styles and style classes.
There is a set of standard and custom styles which each indicates a particular style. These are guide lines, each editor could implement a standard style in different ways.
Metadata are introduced using @
:
@ + metadata tag + single space + metadata content
Supported metadata:
author
content
description of paragraph contentcreatedAt
updatedAt
A special metadata is the id which can be written in two alternatives ways:
#the-id
@id the-id
the identifiers should be all in lowercase and each word should be separated using
-
.
Style classes are introduced using .
, e.g. .styleClass1
.
In-line styles use CSS (or SCSS/SASS based on editor) key-value modifiers, they haven't a symbol.
To add decorators to a paragraph you must insert {}
in the line below title, in parenthesis each type of decorator has a particular symbol which introduces it. You can use ;
to separate decorator in the same line or a \n
to insert decorator in multiple lines.
There is an example below.
## Foo title
{
#the-id
@author you
@author yourFriend
.styleClass1
background-color: red
}
You can add decorators also to a single word using this syntax:
Style class: table
, table-header
, table-header-row
, table-body
, table-footer
, table-body-row
, table-cell
, table-left-cell
, table-center-cell
, table-right-cell
, table-empty-cell
, table-caption
Each table has an table head, body and footer (like HTML tables). A table can have only head or only footer, but it must always have body.
Standard syntax:
| Syntax | Description | Test Text |
| :--- | :----: | ---: |
| Header | Title | Here's this |
| Paragraph | Text | And more |
:---
for column left alignment
---:
for column right alignment
:---:
for column center alignment
Extended syntax
| Syntax :| Description |: Test Text :|
| :--- | :----: | ---: |
| Header :| Title | Here's this |
| Paragraph | Text :| And more |
|---|
|| Footer |
[Caption]#table-id{style}
:
to specify cell alignment
:---
for column left alignment
---:
for column right alignment
:---:
for column center alignment