Skip to content

Markdown Tips and Tricks

Links

See also:

A basic link is done like so:

[pwrp](http://powerpartners.pro)

This will render like so: pwrp.

Within the scope of a single mkdocs.yml file, you can reference pages by title, e.g.:

[[fix-this-next|Fix This Next]]

...which renders as Fix This Next.

Internally, the following happens:

  1. The name between double square brackets is translated to fix-this-next.md

  2. The ezlinks plugin tries to find the "closest" file named fix-this-next.md

  3. If found, a link to the page originating from the file is generated

Hence, we recommend to always name your files the same as the file name, and to be as explicit as possible with the file names. e.g.

  • Fix this Next in the title
  • fix-this-next.md as file name

You can also link by file name:

(Overview)[index.md]

...which renders as departments/delivery/knowledge-base/md/introduction.

This is achieved with the ezlinks plugin for mkdocs.

Table

The best way to render tables is with VSC, using the plugin "TakumiI.markdowntable".

Syntax:

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

To work in VSC, proceed as follows:

  1. select "Spaces" on the bottom right of VSC

  2. define "Tab"

  3. enter your table with tabs

  4. select table in document, and hit Ctrl+Shift+P

  5. select Convert TSV to table

  6. use Alt+Shift+Mouse to select or delete columns

  7. use Tab to navigate and re-format the table

  8. use the context menu to add column

tab-tables.png

Images

An image is inserted like so:

![[paste-image.png]]

The best is to use telesoho.vscode-markdown-paste-image in VSC.

Proceed as follows:

  1. make sure the image is in your clipboard

  2. in VSC, go to the document where you want to add an image

  3. go to the place where you want to insert the image

  4. hit Ctrl+Shift+P

  5. run Markdown Paste

  6. the extension will suggest an image name

    paste-image.png

  7. replace the number with the image name, making sure to also add resources. This will make sure that the file will be stored in the resources subfolder

    paste-image-target.png

Code Blocks

Code blocks are marked with backticks: `

Block

A fenced code block is marked with three backticks:

    ```
    var x = FALSE()
    ```

var x = FALSE()

Inline

You can also mark a variable in-line, enclosing it in backticks:

This is a `variable`.

This is a variable.

Titles

### Header of level

Start every md file with a h1 title (e.g. # Finacc BC Overview). Then, it will be taken by mkdocs as a title of the page. Be explicit with your title (e.g. Finacc BC Overview instead of just Overview). Also, you may then reference the page like so: [[finacc-bc-overview|Finacc BC Overview]]. However, if the page title is not unique, then the "closest" page having that title will be referenced.

For details, see the ezlinks mkdocs plugin.

Mermaid

Callouts

Obisidan Callouts

You can use the obsidian callout functionality.

Title

This is a callout

You can use:

> [!tip]- A collapsed tip
> Hello there!

The following types of callouts are available:

  • note (blue)
  • abstract, summary, tldr (green)
  • info (blue)
  • todo (blue)
  • tip, hint, important (sky blue)
  • success, check, done (green)
  • question, help, faq (yellow)
  • warning, caution, attention (orange)
  • failure, fail, missing (red)
  • danger, error (red)
  • bug (red)
  • example (purple)
  • quote, cite (grey)

mkdocs admonitions

In mkdocs, callouts are called admonitions. The notation is different (see below). But we make sure that our obsidian callouts are automatically converted to mkdocs-material admonitions when the website is built.

See here: https://squidfunk.github.io/mkdocs-material/reference/admonitions/

Note

> [!Note] My Note
> This is a note box

My Note

This is a note box

Types

> [!TIP] My Tip
> This is a tip box

My Tip

This is a tip box

My Info

This is an Info box

My Question

This is a question?

My Warning

This is a warning

My Bug

This is a bug box

My Example

This is an example

My Danger

This is a danger box

My Failure

This is a failure

My Quote

This is a quote

My Abstract

This is a abstract box

The types are:

  • NOTE

  • ABSTRACT

  • INFO

  • TIP

  • SUCCESS

  • QUESTION

  • WARNING

  • FAILURE

  • DANGER

  • BUG

  • EXAMPLE

  • QUOTE

Collapsible Folding

A plus sign expands the callout by default, and a minus sign collapses it instead.

> [!ABSTRACT]+ My Unfolded Abstract
> This is a abstract box
My Unfolded Abstract

This is a abstract box

My Folded Abstract

This is a abstract box