1. What is Markdown

Markdown is a language focused on simplicity and lightweight markup for writing documents. As you well know, writing a page in HTML is complicated, not very readable since you find symbols specific to the language, opening and closing tags, etc…

Markdown aims to be a much simpler language, with marks to indicate the most general aspects (headline, bold, image, etc..).

The ease of handling and writing markdown documents has made it quickly adopted by many editors. This has originated the growth of Markdown parsers to other more complex languages, for example there are interpreters that from a Markdown document are able to generate the resulting HTML code, or generate a .doc file, generate an epub, etc…

2. Examples of blocks in markdown

This page shows examples of utilities that can be used:

Important: Full compatibility is with the material theme

Including javascript code

You can always include your code in the md itself and it will be interpreted

<script>
  window.addEventListener('load', function () {
    alert("I am including javascript code")
  });
</script>

Editing your Mkdocs code

We can make it so you can edit the page you are viewing directly.

For this it is as simple as making sure to:

• Have the repo_url property in your mkdocs.yaml: For example: repo_url: https://github.com/example/repository/
• Enable the theme.feature ( content.action.edit) theme: features: - content.action.edit

This will not only add the edit button but will also show the github icon (or the SCM being used)

The official documentation is here https://www.mkdocs.org/user-guide/configuration/#edit_uri

Creating links

https://editormarkdown.com

Or if they are links to this same page

Take me to Drawing flows (For this option the nav section must be registered in mkdocs.yaml)

Send me an email me@email.com

Information blocks

I regret leaving this world without trying Facundo’s sunflower seeds

Blockquoted header

This is blockquoted text.

This is a second paragraph within the blockquoted text.

And this is a subparagraph

Horizontal separators (lines)

Icons

There are several icons that come standard and are in the .icons folder and its subdirectories.

To use them just indicate the subdirectory path instead of with slash using hyphens

:fontawesome-solid-angry: we are using the icon in the path .icons/fontawesome/solid/angry.svg (since we are using the docker image we cannot explore the icons directory, but it can be consulted by downloading the mkdocs material code)

(this icon belongs to .icons/material/material-design.svg)

This icon is in .icons/octicons/key-16.svg

Include styles in your page to customize your icons

– Medium

Ordered lists

1. First element
2. Second element
3. Third element

Unordered lists

• option A
• option B
• option C

Highlighted code

• ==This was marked==
• ^^This was inserted^^
• ~~This was deleted~~

Collapsed blocks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

version: '3.7'
networks:
  local:
    external: true
services:
  postgres11:

volumes:
  postgresql:
  postgres11-data:
    driver: local

Drawing Flows

Using mermaid https://mermaid.js.org/config/theming.html

Sequence diagram

Drawing charts

Using Vegalite plugin (documentation here https://vega.github.io/vega-lite/examples/) For this to work it is necessary to have an index.md page at the root I don’t know why, but it is

{ "description": "A simple bar chart with embedded data.", "data": {"url" : "https://raw.githubusercontent.com/timvink/mkdocs-charts-plugin/main/docs/assets/charts/data/basic_bar_chart.json"}, "mark": {"type": "bar", "tooltip": true}, "encoding": { "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}}, "y": {"field": "b", "type": "quantitative"} } }

{ "$schema": "https://vega.github.io/schema/vega-lite/v5.json", "description": "Google's stock price over time.", "data": {"url": "https://vega.github.io/vega-lite/data/stocks.csv"}, "transform": [{"filter": "datum.symbol==='GOOG'"}], "mark": "line", "encoding": { "x": {"field": "date", "type": "temporal"}, "y": {"field": "price", "type": "quantitative"} } }

Using Tables

Using Tabs

Creating checklists

• Lorem ipsum dolor sit amet, consectetur adipiscing elit
• Vestibulum convallis sit amet nisi a tincidunt
  • In hac habitasse platea dictumst
  • In scelerisque nibh non dolor mollis congue sed et metus
  • Praesent sed risus massa
• Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Images with text alongside

As we can see in the photo next to us it shows an empty image from the site http://dummyimage.com.

Another paragraph also next to the photo.

If we want to start writing below the photo, we must insert as many ‘< br />’ as we need until we exit.

I’m already out in the next paragraph, you see?.

Images with caption

Generating the static site

If we want to generate the static site

docker run --rm -it -p 9999:8000 -v /home/dpena/Documentos/deadveloper/Guias:/docs danipenaperez/mkdocs  build

Then deploy them on some static code server or on gh-pages. For example here we use nginx to test deploying the generated statics

docker run -it --rm -d -p 8080:80 --name borrame -v /home/dpena/Documentos/deadveloper/Guias/site:/usr/share/nginx/html nginx
sensible-browser http://localhost:8080

Other themes

This one looks good https://github.com/ppoffice/hexo-theme-icarus

Generating footers