Markdown Toolbox Logo Markdown Toolbox
Maison
Blog

Guide de syntaxe Markdown : techniques de formatage avancées

2024-02-19

Markdown Syntax Guide: Advanced Formatting Techniques

Most likely everyone will agree that mastering advanced Markdown syntax can be challenging when creating technical documents.

Well, this guide will walk you through essential advanced formatting techniques like tables, footnotes, highlighted code blocks, and more...

...allowing you to craft polished, professional-grade Markdown documents.

You're going to learn precise syntax for elements like:

  • Formatting complex tables with alignment, emphasis, and images
  • Embedding and customizing images with captions and sizing
  • Showcasing code samples with syntax highlighting and line numbers
  • Linking headings for improved document navigation
  • And leveraging extended syntax like task lists and emojis

Mastering Markdown: An Advanced Syntax Guide

Markdown is a lightweight markup language that allows you to write using simple plaintext syntax, which is then converted to HTML. While basic Markdown syntax is easy to learn, there are more advanced formatting options that allow you to create even more polished and professional documents.

In this guide, we'll explore some of Markdown's more advanced formatting features to take your documents to the next level.

Creating Tables

Tables are a great way to present information in an organized way. To create a table in Markdown, you'll need to use pipe (|) characters to separate each column, and hyphens (-) to create column headers:

| Syntax | Description |  
| ------------- |:-------------:|
| Header | Title |
| Paragraph | Text |

Which would render as:

Syntax

Description

Header

Title

Paragraph

Text

You can align text in the columns left, right or center by adding colons (:) next to the hyphens on that side.

Adding Footnotes

Footnotes allow you to reference information in the document without cluttering up the main text. To create a footnote reference, add brackets with a caret and number inside [ˆ1]. Then at the bottom, add the footnote content prefixed with the number and colon:

Here is some text with a footnote[^1].

[^1]: Here is the footnote content!

This helps annotate text without being too intrusive.

Embedding Images

Adding images helps illustrate concepts visually. To embed an image, use an exclamation point, followed by alt text in brackets, and the image URL in parentheses:

![alt text](imageurl.jpg)

You can also specify optional width and height values after the URL to control sizing:

![alt text](imageurl.jpg =250x250)

And don't forget to include useful alt text for accessibility!

How do I write code in Markdown?

To write code or code blocks in Markdown, you have a couple of options:

Use backticks

You can wrap your code in backticks ``` to create an inline code snippet or to create a distinct code block.

For example:

`inline code snippet`

Will display as:

inline code snippet

For larger code blocks:

```
// code block
var x = 10;
console.log(x); 
```

Will display as:

// code block 
var x = 10;
console.log(x);

The backticks allow your code to retain original formatting and stand out from normal text.

Indent code blocks

Alternatively, you can indent code by 4 spaces to create a distinct block:

// indented code 
var x = 10;
console.log(x);

This achieves the same effect of making code stand out and retaining formatting.

Syntax highlighting

To add syntax highlighting for specific languages, specify the language after the opening backticks:

```js
// javascript code
var x = 10; 
console.log(x);
```

Which will show colored syntax highlighting for JavaScript.

So in summary, use backticks for inline code and 4 space intenting or fenced code blocks for larger snippets. Syntax highlighting also helps code stand out.

What is syntax Markdown?

Markdown is a lightweight markup language that allows users to add formatting elements to plain text documents without needing to use a dedicated word processor or HTML. Some key aspects of Markdown syntax include:

Formatting Text

  • Bold and italic text can be created by surrounding words with double asterisks (**) or single asterisks (*) respectively.
  • Headings are denoted using the hash (#) symbol, with the number of hashes indicating heading size. For example:
# Heading Level 1
## Heading Level 2
### Heading Level 3 
  • Lists can be created by prefacing each item with a dash (-) for unordered lists or a number for ordered lists.
  • Links are written in square brackets, with the URL in parentheses immediately after, like this [link text](https://example.com).
  • Images are added similarly using an exclamation point instead of brackets: ![alt text](imageURL).

Code Blocks

  • Code blocks are created by indenting each line by 4 spaces or fencing the block in triple backticks (```).

In summary, Markdown offers a fast way to format documents without needing to toggle between writing and reviewing visual styles. Its simple syntax helps boost productivity for technical writers, developers, students, and more.

How to structure Markdown?

Markdown allows you to add structure to documents in a few key ways:

Headings

Headings in Markdown are created by prefixing text with the # symbol. The number of # symbols indicates the heading level:

# Heading 1 
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Headings help create an outline and hierarchy for your document.

Lists

Markdown supports both numbered and bulleted lists:

1. First item 
2. Second item
3. Third item

  • First item
  • Second item
  • Third item

Lists help organize related items into groups.

Horizontal rules

You can create a horizontal rule/divider by using three or more asterisks ***, dashes ---, or underscores ___ on a line by themselves:

***



Horizontal rules help visually separate sections of a document.

Tables

Tables can be created in Markdown by using pipes | and hyphens -:

| Column 1 | Column 2 | Column 3 | 
| -------- | -------- | -------- |
| Row 1    | Data     | Here     |
| Row 2    | More     | Data     |

Tables allow displaying data in rows and columns.

In summary, headings, lists, horizontal rules, and tables provide structure and organization in Markdown documents. They help separate ideas, outline content, and present data in an easy-to-scan format.

How do you style a Markdown code?

To format a code block in Markdown, you need to indent every line of the code by at least 4 spaces. This creates a fenced code block that is formatted properly with syntax highlighting.

Here is an example Markdown code block:

```js
function helloWorld() {
  console.log("Hello World!");
}
```

Some key things to note about Markdown code blocks:

  • The opening and closing triple backticks ``` indicate the start and end of a fenced code block.
  • There should no spaces between the backticks and the code language (js in the example above).
  • The indented code cannot interrupt a paragraph in Markdown. You need to have a blank line before and after a fenced code block.
  • Indenting by 4 spaces also works for formatting code, but fenced code blocks are preferred as they allow you to specify a coding language for syntax highlighting.
  • For indented code blocks, if you indent lines by less than 4 spaces, Markdown will think it is a continuation of the same paragraph.

So in summary, use fenced code blocks with a specified language for proper formatting and highlighting of code in Markdown documents. The code must either be indented by 4 spaces as a block, or fenced with opening and closing triple backticks.

Enhancing Readability with Markdown Tables

Markdown tables allow you to present information in a clean, organized way that is easy for readers to scan and comprehend. However, crafting Markdown tables requires understanding some key syntax and techniques.

Mastering Markdown Table Syntax

To build a basic Markdown table, you use pipes (|) to separate each column and hyphens (-) to create column headers. For example:

| Header 1 | Header 2 | Header 3 | 
| -------- | -------- | -------- |
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |

You can align text to the left, center, or right by adding colons (:) next to each header:

| Left aligned | Center aligned | Right aligned |
| :-- | :-: | --: |

Alignment and Emphasis in Tables

Adding formatting like bold or italics within Markdown table cells can help emphasize important elements:

| **Product** | **Price** | 
| ----------- | --------- |
| *Apples* | $2 |
| *Oranges* | $1 | 

Escaping Pipe Characters in Markdown Tables

If you need to include a pipe (|) character within a table cell, escape it by adding a backslash (\) before the pipe:

| Column 1 | Column 2 | 
| -------- | -------- |
| Cell \| with escaped pipe | Other cell |

Automating Table Creation with Markdown Tables Generator

For complex Markdown tables, use an online Markdown Tables Generator to simplify formatting instead of building tables manually.

Adding Image Captions and Size Specifications

Include images in Markdown tables and define custom sizes. Add captions by referencing image alt text:

![Alternate text](image.jpg){: style="width:40%"}

Figure 1: Alternate text for caption

With these advanced table formatting techniques, you can build highly customized and readable Markdown tables for any purpose.

sbb-itb-0cbb98c

Embedding and Customizing Images

Embedding images into Markdown documents allows you to enhance visual appeal and clarity. With some key syntax and configuration, images can be sized, aligned, captioned, and linked for maximum flexibility.

Markdown Syntax for Embedded Images

The basic Markdown image syntax is:

![alt text](image url)

The alt text provides a description for screen readers and if the image fails to load. Use clear, concise phrases.

Image URLs can be relative or absolute paths or full web URLs. Using a relative path is recommended for portability.

Controlling Image Size and Alignment

Additional Markdown syntax can customize image sizing and alignment:

<img src="image.jpg" width="300" height="200" align="left">
  • Use pixel values for width and height to control dimensions
  • The align value controls image placement: left, right, or center

This ensures images fit within content flow as intended.

Creating Image Captions with Extended Syntax

Markdown extensions like MultiMarkdown have a handy image caption syntax:

![alt text][id]

[id]: relative/url/to/image "Optional caption text"

The id links the image to its caption text placed below it.

Linking Images to External Content

Turn images into links by wrapping Markdown link syntax:

[![alt text](image.jpg)](https://example.com)

When clicked, the image links out to the specified URL.

Previewing Embedded Images with Markdown Preview Tools

Most Markdown editors provide a preview mode to validate how images will render in HTML. Use it to:

  • Confirm images are sized and placed correctly
  • Test caption linkage
  • Ensure alt text works if images fail to load

Checking image formatting in preview helps avoid issues when publishing.

Utilizing Footnotes for Detailed Explanations

Footnotes are a useful way to provide additional context or commentary without disrupting the main text flow. The Markdown syntax for footnotes is straightforward:

Implementing Footnotes in Markdown Documents

To create a footnote reference, add a caret and number in brackets like this: [^1]. Then at the bottom of your document, add the footnote content prefixed by the number and colon.

For example:

Here is some text with a footnote reference.[^1]

[^1]: Here is the footnote content explaining the reference.

The syntax keeps footnotes unobtrusive so readers can easily skip over them if desired.

Multi-Paragraph Footnotes for Extensive Commentary

You can include multiple paragraphs in a footnote to provide more details. Separate paragraphs with a blank line. For example:

Main document text.[^1]

[^1]: Paragraph 1 of the footnote explaining something in detail.

Paragraph 2 adding more context in the footnote.
</code></pre>

This allows expansive footnotes without lengthy tangents in the main text.

Managing Footnote References Efficiently

When using multiple footnotes, you can reuse footnote references rather than creating new ones. For example:

Reusing a reference.[^1]

Explaining something else.[^1]

[^1]: Footnote with details about both references.

You can also keep references organized by defining each one separately.

Customizing Footnote Appearance and Placement

For more customization of footnote styling and layout using CSS, some popular Markdown extensions like Markdown Extra allow additional control. You can tweak font sizes, indentation, spacing, borders and more.

Placement of footnotes in the rendered output depends on your processor. Some will push them to the bottom by default while others keep them inline. Check your processor's settings if you need to adjust layout.

Showcasing Code with Markdown Syntax Highlighting

Creating Fenced Markdown Code Blocks

Fenced code blocks in Markdown allow you to organize and display code snippets cleanly, with automatic formatting to distinguish the code from regular text. To create a fenced code block, surround your code with three backticks ``` on the lines before and after the code block. For example:

​```js
let name = "John";
console.log(`Hello ${name}!`); 
​```

Will display the JavaScript code properly formatted. You can also specify the programming language after the opening backticks for syntax highlighting.

Applying Syntax Highlighting to Code

Adding syntax highlighting makes code blocks easier to read and understand. Many Markdown processors will automatically apply highlighting to fenced code blocks if you specify the language. For example:

​```python
def hello(name):
  print(f"Hello {name}!")
​```

Will display the Python code with keywords, strings, and other elements color coded. Check your Markdown renderer's documentation for supported languages.

Enhancing Code Blocks with Line Numbering

Line numbers are useful for discussing code examples. To add line numbers in Markdown, append {linenos} to the opening backticks, like:

​```python {linenos} 
def hello(name):
  print(f"Hello {name}!")
​```

This will number each line down the left gutter of the code block.

Adding Copy Buttons to Code Blocks

For user convenience, some Markdown platforms allow adding copy buttons to code blocks, to easily copy the full code snippet with one click. Check your renderer's options, as this is commonly available in many Markdown editors now.

Deep Linking with Markdown Heading IDs

Deep linking allows readers to easily navigate to specific parts of a Markdown document by linking directly to heading IDs. This enhances document usability and improves the reading experience.

Many Markdown editors like Markdown Toolbox automatically generate IDs for each heading, making it easy to link to sections without any extra effort. The IDs are generated based on the heading text.

For example, for the heading "Introduction", the ID would be "introduction". You can then link to this section using [Introduction](#introduction). This saves time compared to manually creating IDs and ensures consistency in linking.

Customizing Heading IDs for Targeted Navigation

You may want to create custom heading IDs instead of relying on auto-generated ones. This gives you full control over the ID naming scheme.

For example, you could use ## <a id="intro"></a>Introduction to create the ID "intro" instead of "introduction". Then link with [Introduction](#intro).

Custom IDs are useful when:

  • You want a short, predictable ID that's easy to remember
  • You need to refer to a section in multiple documents
  • Auto-generated IDs are too long or change when headings change

Here are some tips for working with heading IDs and link targets in Markdown:

  • Keep IDs short, lowercase, and descriptive
  • Avoid spaces, special characters, and numbers in IDs
  • Use consistent ID naming schemes across documents
  • Link to IDs using inline link or reference link Markdown syntax
  • Test links after any heading text changes to prevent breakage

Following Markdown heading ID best practices improves document structure and navigation.

Linking to Heading IDs in Practice

Linking to heading IDs helps:

  • Create in-document links to allow quick access to key sections
  • Improve technical documentation navigation
  • Build site table of contents linking to sections
  • Refer readers to related content within blog posts
  • Let readers share links to specific parts of documents

For example, a blog post could link to sections of a tutorial for more details, rather than reiterating the information.

Overall, leveraging heading IDs facilitates easy content navigation, helping enhance the reader experience.

Leveraging Extended Markdown Syntax for Advanced Formatting

Markdown offers a robust set of basic formatting options like headings, lists, links, and code blocks. However, many Markdown implementations build on this foundation by adding extended syntax for even more advanced capabilities. Exploring these extended Markdown features unlocks new possibilities for creating professional, dynamic documents.

Incorporating Task Lists and Emojis

Task lists provide an interactive element that allows readers to check off items as they are completed. This drives engagement and makes Markdown documents more functional. Here is an example task list:

  • [ ] Learn Markdown syntax
  • [x] Practice using extended Markdown features
  • [ ] Create document with advanced formatting

Emojis can also add visual flair and help highlight important points or actions. For example:

See the :bulb: icon? It calls attention to a key idea. The :rocket: emoji signifies an important next step.

Use emojis judiciously, as overuse can become distracting. But when used effectively, they can aid comprehension and recall.

Utilizing Superscript, Subscript, and Highlighting

Superscript creates smaller raised text, which is useful for footnotes\[1\] or mathematical equations like x2. Subscript lowers text below the baseline, helpful for chemical formulas like H2O. Highlighting draws attention to text in yellow, which can emphasize key terminology.

These text formatting options improve clarity, allowing writers to add levels of meaning. Use them strategically to call attention to critical information.

Exploring GitHub Flavored Markdown (GFM) Features

GFM builds on standard Markdown by adding useful functionality like tables, task lists, and strikethrough text. For example, this strikethrough shows deleted text, helping track changes.

GFM also enables creating Markdown tables using pipes and hyphens. Tables keep related data organized and scannable:

Name

Description

John

Manager

Jane

Developer

These features streamline workflows for technical writers and developers collaborating on GitHub.

Advanced Attributes and Syntax with Markdown Extra

For even more control over Markdown documents, Markdown Extra offers additional syntax like defining custom ID anchors and automated table of contents generation.

For instance, linking directly to headings is possible by assigning them custom IDs like so:

My Heading {#custom-id}

Then linking with:

Jump to Heading

Markdown Extra also auto-generates tables of contents based on headings:

[TOC]

This advanced functionality takes Markdown authoring to the next level for creating long, complex documents.

By leveraging extended Markdown syntax, technical writers, developers, and content creators can build feature-rich, professional-grade documents tailored to their needs. The possibilities are vast with these robust formatting tools.

Conclusion: Crafting Polished Documents with Advanced Markdown

Advanced Markdown formatting techniques allow you to create more polished, professional documents. Key takeaways covered in this guide include:

  • Tables: Formatting data into tables allows for clearer presentation of information. Techniques like escaping the pipe character allow you to include markdown syntax within tables.
  • Footnotes: Adding footnotes or endnotes to your documents enables you to provide additional context without interrupting the main text.
  • Embedded Images: Embedding images into your Markdown files can visually enhance your documents. Properly sizing images and adding captions improves readability.
  • Linking to Heading IDs: Creating anchors to link to specific headings makes it easy for readers to navigate longer documents.
  • Extended Syntax: Leveraging extended syntax like fenced code blocks, strikethrough text, task lists, and more unlocks additional formatting options.

Mastering these advanced techniques empowers you to produce highly polished and professional documents in Markdown. The result is content that looks great and effectively communicates information to your readers.