LaTex2Web logo

LaTeX2Web, a web authoring and publishing system

If you see this, something is wrong

Collapse and expand sections

To get acquainted with the document, the best thing to do is to select the "Collapse all sections" item from the "View" menu. This will leave visible only the titles of the top-level sections.

Clicking on a section title toggles the visibility of the section content. If you have collapsed all of the sections, this will let you discover the document progressively, from the top-level sections to the lower-level ones.

Cross-references and related material

Generally speaking, anything that is blue is clickable.

Clicking on a reference link (like an equation number, for instance) will display the reference as close as possible, without breaking the layout. Clicking on the displayed content or on the reference link hides the content. This is recursive: if the content includes a reference, clicking on it will have the same effect. These "links" are not necessarily numbers, as it is possible in LaTeX2Web to use full text for a reference.

Clicking on a bibliographical reference (i.e., a number within brackets) will display the reference.

Speech bubbles indicate a footnote. Click on the bubble to reveal the footnote (there is no page in a web document, so footnotes are placed inside the text flow). Acronyms work the same way as footnotes, except that you have the acronym instead of the speech bubble.

Discussions

By default, discussions are open in a document. Click on the discussion button below to reveal the discussion thread. However, you must be registered to participate in the discussion.

If a thread has been initialized, you can reply to it. Any modification to any comment, or a reply to it, in the discussion is signified by email to the owner of the document and to the author of the comment.

Table of contents

First published on Wednesday, Jun 5, 2024 and last modified on Wednesday, Jan 15, 2025 by François Chaplais.

Markdown Tutorial

François Chaplais WebMagic, maker of LaTeX2Web

1 Background

1.1 Summary

Markdown is a plain text syntax that allows to layout structured documents while preserving (to a certain extent) source code compatibility. Markdown stands between rich text notes and more complex formats, such as Web or PDF documents.

This document presents the best known features of markdown.

1.2 Software

I recommend the use of Joplin, which is a free, open source, markdown editor. It runs on Windows, macOS, Linux, Android and iOS. Joplin notes can be synced through Dropbox and OneDrive.

For a small monthly fee, you can have access to Joplin Cloud. It features

  • fast cloud syncing of Joplin notes

  • hosting of published notes (with a sharable link on the web)

  • a convenient clipper extension for Chrome compatible browsers.

  • published notes are automatically synced with your local Joplin notes.

  • Joplin cloud users can share notebooks between them

Plugins for Joplin are also available.

This note was written in Joplin.

2 Syntax

There is a documentation for GitHub flavored Markdown here: GitHub Flavored Markdown Spec

2.1 Elementary syntax

The following are supported by most markdown applications.


2.1.1 Document structure

2.1.1.1 Heading

Headings (or sections) are created by insterting one or several hashtags # at the beginning of a line, followed by a space and the text of a heading.

The number of # indicates the level of nesting. For instance #### Heading is a heading of level 4.

2.1.1.2 Paragraph

To create a new paragraph, insert a blank line.

(This is the second paragraph)

2.1.1.3 Line break

To create a line break,
just insert a line termination character without the empty line.

2.1.1.4 Quote

to insert a quote, just put the > character at the beginning of the line followed by a space
like this > like this

2.1.1.5 Quotation with multiple paragraphs

It works just as before, except you have to insert blank lines preceded by >

We must let go of the life we have planned, so as to accept the one that is waiting for us.

Joseph Campbell

2.1.1.6 Horizontal rule

just insert a line beginning with several hyphens: ---. Separate the code text by blank lines. This is used in this document!

2.1.1.7 Lists

Unumbered lists are created by using an asterisk ( * ) followed by a space at the beginning of each line. Lists can be nested by interting 4 spaces or a tab character before the asterisk. The code

* Milk
* Bread
* Cheese
	* Roquefort
	* Camembert
* Rice

gives

  • Milk

  • Bread

  • Cheese

    • Roquefort

    • Camembert

  • Rice

Numbered lists work like unumbered lists except that you replace the asterisk with a number followed by a dot.
The code

1. Milk
1. Bread
1. Cheese
	1. Roquefort
	1. Camembert
1. Rice

gives

  1. Milk

  2. Bread

  3. Cheese

    1. Roquefort

    2. Camembert

  4. Rice

Lists can contain list markdown elements. Here is a list of links (see section below about links)

The code is

* [Joplin](https://joplinapp.org/)
* [Marked 2 - Smarter tools for smarter writers](https://marked2app.com/)


2.1.2 Styling

DescriptionMarkdown codeOutput
Bold text**Bold**Bold
Italic*Italic*Italic
Bold Italic***Important***Important
CodeThis is `some code` This is some code


2.1.3 Links and similar

2.1.3.1 Web links

This is how the link to the Joplin home page was coded
[Joplin](https://joplinapp.org/)
In the two brackets at the beginning is the text that will be displayed.
Between the two parentheses is the actual web address.

You can also style your links:
[*Joplin*](https://joplinapp.org/ "An awesome Markdown editor") gives
Joplin

For email, the following code
[email me](mailto:[email protected]) gives
email me


2.1.4 Images

Images cannot be stored inside a Markdown text file. This means that the image must be stored elsewhere. This why the syntax is the same for a web link, with the difference that an exclamation mark ! is just before the image link.
The code ![Alfred E. Neuman](https://www.dropbox.com/scl/fi/emssrbp6ryug2qaznjgud/Like-Mad.jpg?rlkey=q612dw4dw9ab5wct488g2vmg8&raw=1) displays the following image:

Alfred E. Neuman
Alfred E. Neuman

The text inside the bracket is an alternative text description of the image, which is useful when the link to the image does not work.

Not only can you display an image, you can also make it a link. To do so you enclose the image inside brackets (as if it was the text of a link) and append the address of the link between parentheses.
Using the code [![Joplin](https://www.dropbox.com/scl/fi/niucosis01vur3vskw84a/Joplin-2x.png?rlkey=18twvivdflvu4l7m9ymz0ve92&raw=1)](https://joplinapp.org) we generate an image with a link to the Joplin site (I love Joplin!)


2.2 Extended syntax

Extensions of the markdown syntax which are commonly used in advanced markdown editors are described here. Code that does not work in Joplin is highlited.


2.2.1 Special characters

As in most languages, Markdown has its own reserved characters that you cannot simply display in the code output.
These characters are

  • \\

  • `

  • *

  • _

  • { and }

  • [ and ]

  • ( and )

  • #

  • +

  • -

  • . (dot)

  • !

  • | (pipe)

To display them, you have to put a backslash \  before the character. For instance, to display an asterisk character, the code is \* .


2.2.2 Tables

2.2.2.1 Syntax

The table that describe the syntax for Markdown text styling was obtained by using the following markdown code:

| Description | Markdown code | Output |
| ---------- | :--------------: | ------ |
| Bold text | **Bold**| **Bold** |
| Italic | *Italic*| *Italic* |
| Bold Italic | ***Important***| ***Important*** |
| Code | This is `some code` | This is some code |

Observe the use of the tick `character to create embedded code in the text. The double tick `` is used to embed markdown code that precisely contains the tick character.

2.2.2.2 Alignment

Using colons : is the separating line created by the hyphens - characters controls the alignment of the text in the corresponding:

  • for one : at the left the column is left justified (default)

  • for one : at the right the column is right justified

  • for a : at each side of the hyphens, the column is centered justified (see second colum in the example above).

2.2.2.3 Formatting Text in Tables

You can format the text within tables. For example, you can add links, code (words or phrases in backticks ( ` ) only, not code blocks (see section below)), and emphasis.
You can’t add headings, blockquotes, lists, horizontal rules, images, or HTML tags.


2.2.3 Fenced Code Blocks

To embed blocks of code in markdown, you just have to put before and after the markdown code a line with the triple tick ( ``` ) of three tildes ( ~~~ ). This is how the code of the styling table was exhibited in the previous section. Here is an example

```
This is my markdown code
```

This code display was itself coded using triple tildes!

In some editors, specifing the language just after the first triple tick invokes syntax coloring. Here is an HTML example:

<p>
 The link is specified as before, but a <b>target</b> attribute is added
 with value <b>_blank</b>. Here is an
 <a href="Lists.html" target="_blank">internal link</a>.
</p>


2.2.4 Footnotes

A footnote is made of two parts. Both parts must be in the same paragaph.
The first part define the location and reference of the footnote. To create it, add a caret and an identifier inside brackets: [^identifier] .
Here is some text with a footnote link .
The content of the footnote content is [^identifier]: the footnote text where the content ends with the next newline character.


2.2.5 Definition Lists

You can use "definitions" by putting a colon followed by a space at the beginning of the text:
: This is the definition of the first term. .

First Term
This is the definition of the first term.

Second Term
This is one definition of the second term.
This is another definition of the second term


2.2.6 Strikethrough

Using double tilde ~~ delimiters you can create the following text style:

The following text is invalid.

The code for this is The following text is ~~invalid~~.


2.2.7 Task Lists

To add a task list, begin your lines with a hyphen - followed by a pair of brackets. If a space is inside the brackets [ ] , the checkbox is unmarked. If an x is inside the brackets [x] , the checkbox is marked. Here is an example:

  • Finish the Markdown primer

  • Give a task list example

In Joplin, marking or unmarking the checkboxes in the preview is directly reflected into the source code .


2.2.8 Emoji

Simply paste the emoji in the source to have it displayed in the output. An example follows:

Go to 📙 Emojipedia — 😃 Home of Emoji Meanings 💁👌🎍😍 to learn about emojis. Here is a sample list of emojis:

  • happy face 😀

  • poop 💩


2.2.9 LaTeX

Some markdown processers (like Joplin) render LaTeX code. To display an equation, use the double dollar $$ delimiter. To render Maths inside text (aka LR mode), use single dollar $ delimeters. Here is an example:

Let us display an differential equation in integral form:

\[ x(t)=x_{0}+\int_{0}^{t}f(x(s))ds\]

Now let us put it into text by using the more compact differential form \( \frac{dx}{dt}=f(x)\;\;x(0)=x_{0}\) . The source code is below (using the "LATEX" language specification for syntax coloring):

Let us display an differential equation in integral form:
\[ x(t)=x_{0}+\int_{0}^{t}f(x(s))ds\] 
Now let us put it into text by using the more compact differential form \( \frac{dx}{dt}=f(x)\;\;x(0)=x_{0}\) . The source code is below (using the "LATEX" language specification for syntax coloring):

3 Joplin specifics

3.1 Typography

Special characters are rendered by putting a code inside parentheses. Here is a short list:

  • (c) is obtained with (c)

  • (R) is obtained with (R)

  • (TM) is obtained with (TM)


3.2 Indices and exponents

The tilde ~ delimiter encloses an index. X~1~ yields X1.

The hat ^ delimiter encloses an exponent. X^2^ yields X2.


3.3 Mark

The double equality == delimiter encloses hilighted text. ==marked== yields marked.

4 Export

4.1 PDF export

Joplin exports individual notes to PDF. This is the export option that you should use for PDF, as it will understand all of Joplin specifics (except for media files, which are not supported in the export).

4.2 HTML export

Joplin exports the whole library into a local folder. There is no navigation bar. If you want to publish it online, do not forget to include the "pluginAssets" folder.

4.3 Exports outside Joplin


4.3.1 Media caveat

If you consider exporting your markdown code, please, please, do not drag and drop media files into Joplin. Publish your media files to the cloud and use valid URLs, not tiny URLs like"https://brurb.crap/jZ7bi56MN". These URLs are not robust.

4.3.2 First step: create a single markdown file

The safest export to a markdown file is to

  • copy the markdown source code of your note

  • create a new document in a plain text editor

  • paste the code

  • save the file with a ".md" extension

Then you can open it in an export savvy Markdown application with good export capabilities. Beware that part of the code may work in Joplin but not in other apps. If you want to play it safe, stick to the syntax described in the Elementary syntax section.


4.3.3 On the Mac: export with Marked 2

4.3.3.1 Export options

Marked 2 is a Mac app that previews markdown files and exports them to

  • HTML (although it’s better to use the Joplin export)

  • PDF (everything into one page; use Joplin instead)

  • PDF (Paginated)

  • RTFD

  • RTF

  • DOC

  • DOCX

  • ODT

  • Markdown (!)

  • OPML

4.3.3.2 Styling

Your can chose among several styling options in the application preferences and even import custom CSS style files. This is a substantial benefit with respect to Joplin, which has limited styling capabilities.

The links and styling are respected when exporting when possible, notably for

  • HTML

  • PDF

  • RTFD

5 On the Mac: linking with Hook

Hook is a powerful tool for creating links between documents on the Mac.

How does this fit into Markdown? Well, when you are working on a document, invoke the Hook context window and you will obtain something like this:

Hook window
Hook window

Hit Command-M and paste the code into a markdown editor like Joplin. The most basic usage is for storing Web links. But you can have links to files, mails, etc...

For a full list of supported Mac applications, see Linkable Mac Apps – Hook. I highly recommend this tool!

I am normally hidden by the status bar