Skip to main content

Guide: How to format content using Markdown

Note Icon

This project is created using Docusaurus. Some of the following sections are from the official Docusaurus 2.0 documentation by Meta Platforms, Inc. and is licensed under CC BY 4.0 International.

Docusaurus supports Markdown and a few additional features.

Front Matter

Markdown documents have metadata at the top called Front Matter:

my-doc.md
---
id: my-doc-id
title: My document title
description: My document description
slug: /my-custom-url
---

## Markdown heading

Markdown text with [links](./hello.md)

Regular Markdown links are supported, using url paths or relative file paths.

Let's see how to [see "Contribute" section](06_01_how-to-contribute).
Let's see how to [see "Contribute" section](../06_01_how-to-contribute).

Result: Let's see how to see "Contribute" section.

Images

Regular Markdown images are supported. You have to use the relative path to the image.

![](/../static/img/get-started/get-started-banner-2.png)

Image:

Code Blocks

Markdown code blocks are supported with Syntax highlighting.

src/components/HelloDocusaurus.js
function HelloDocusaurus() {
return (
<h1>Hello, Docusaurus!</h1>
)
}
src/components/HelloDocusaurus.js
function HelloDocusaurus() {
return <h1>Hello, Docusaurus!</h1>;
}

Admonitions (NEW)

For this project we created some custom admonitions. You can use them like this:

Community note example

:::community[ My community note]

This is a community note. It should be used to highlight important information in contributions and articles on the hub.

:::
Eye Icon
Community note

This is a community note. It should be used to highlight important information in contributions and articles on the hub.

Contact note example

:::contact[ Contact note ]

This is a contact note. It should be used to communicate contact information either on a Hub contribution or on a general overview page.

:::
Speech Bubble Icon
Contact note

This is a contact note. It should be used to communicate contact information either on a Hub contribution or on a general overview page.

Hub Note example

:::hub-note[ My hub note]

lorem ipsum dolor sit amet

:::
Note Icon
My hub note

lorem ipsum dolor sit amet

About Note example

:::about[ My About note]

lorem ipsum dolor sit amet

:::
Eye Icon
My About note

lorem ipsum dolor sit amet

Contribute Note example

:::contribute[ Contribute Note ]

lorem ipsum dolor sit amet

:::
Accounts Icon
Contribute Note

lorem ipsum dolor sit amet

Expandable Sections (NEW)

If you have a lot of content, you can use expandable sections to make it more readable. For this we repurposed the HTML <details> and <summary> elements. If you want to create an expandable section you can just use multiple <details> elements with a <summary> element inside - the borders will be adjusted automatically.

<details>
<summary>Toggle me!</summary>

This is the detailed content

You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
</details>
<details>
<summary>Toggle me!</summary>

This is the detailed content

You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
</details>
Toggle me!

This is the detailed content

You can use Markdown here including bold and italic text, and inline link

Toggle me!

This is the detailed content

You can use Markdown here including bold and italic text, and inline link

If you want the borders to have a different color you can include the following style section in the .mdx file.

<style>
{`
details {
border-top-color: black !important;
border-bottom-color: black !important;
`}
</style>

Icon Lists (NEW)

You can use icon lists to make your content more visually appealing. The individual items can be created using the IconListItem component. The component has the following properties:

  • text: The text that is displayed below the title
  • title: The title of the item
  • icon: The path to the icon that is displayed. The icons are stored in the static/img/icons folder.
  • blob: The path to the blob that is displayed. There are 7 different blue blobs and 4 green blobs available in the static/img/icons folder.

The Icons need to be wrapped in an IconList component.

lorem ipsum dolor sit amet

<IconList>
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " title="Anonymisation" icon="/img/icons/Icon_Anonymisation.png" blob="/img/icons/blue-blob-1.svg" />
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " title="Data-Minimisation" icon="/img/icons/Icon_Data-Minimisation_.png" blob="/img/icons/blue-blob-2.svg" />
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " title="Data-Retention" icon="/img/icons/Icon_Data-Retention.png" blob="/img/icons/blue-blob-3.svg" />
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " title="Safe-Data-Storage" icon="/img/icons/Icon_Safe-Data-Storage.png" blob="/img/icons/blue-blob-4.svg" />
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " title="Harm-Mitigation" icon="/img/icons/Icon_Harm-Mitigation.png" blob="/img/icons/blue-blob-5.svg" />
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " title="Icon_Advocacy" icon="/img/icons/Icon_Advocacy.png" blob="/img/icons/blue-blob-6.svg" />
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " title="Funding-Transparency" icon="/img/icons/Icon_Research-Funding-Transparency.png" blob="/img/icons/blue-blob-7.svg" />
</IconList>
Anonymisation
Anonymisation
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
Data-Minimisation
Data-Minimisation
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
Data-Retention
Data-Retention
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
Safe-Data-Storage
Safe-Data-Storage
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
Harm-Mitigation
Harm-Mitigation
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
Icon_Advocacy
Icon_Advocacy
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt
Funding-Transparency
Funding-Transparency
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt

You can also create icon items without an icon or a title.

<IconList>
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " blob="/img/icons/blue-blob-1.svg" />
<IconListItem text="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt " blob="/img/icons/green-blob-2.svg" />
</IconList>


Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt


Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt

Custom components (NEW)

For this project we created some custom components that can be used in the markdown files. Make sure to use .mdx files for this. You can rename your .md files to .mdx files to use the custom components.

Author Card

You can use the AuthorCard component to display information about the author of a contribution. The component has the following properties:

  • name: The name of the author
  • avatarSrc: The path to the avatar of the author
  • position: The position of the author
  • website: The website of the author
  • linkedin: The LinkedIn profile of the author
  • twitter: The Twitter / X profile of the author
  • mastodon: The GitHub profile of the author
  • scholar: The Google Scholar profile of the author
<AuthorCard
name="Open Knowledge Foundation"
avatarSrc={require("@site/static/img/contributors/okfn.png").default}
position="OKFN"
website="https://okfn.org/en/"
linkedin="https://www.linkedin.com/company/okfn/"
/>

Article Card

You can use the ArticleCard component to display information about an article or research. The component has the following properties:

  • heading: The heading of the article
  • author: The author of the article
  • teaser: A short teaser text about the article
  • link: The link to the article
  • organization: The organization of the author
<ArticleCard 
heading="OSoMe Toolkit for Social Media Research"
author="Indiana University Observatory on Social Media"
organization="Indiana University"
teaser="Exciting tools created by the OSoMe team made available for research, such as the OSoMe Mastodon Search or tools for network visualization and annotation.Take a look!"
link="https://osome.iu.edu/resources/tools"
/>
OSoMe Toolkit for Social Media Research
by Indiana University Observatory on Social Media | Indiana University
Exciting tools created by the OSoMe team made available for research, such as the OSoMe Mastodon Search or tools for network visualization and annotation.Take a look!
Read more arrow right

Chips

There are three kind of chips available: LevelChip to indicate which level of programming experience this article is suitable for, LanguageChip which indicates the programming language and PlatformChip which indicates which social media platform the article relates to. You can use them like this:

<LevelChip level="Beginner" />
<LanguageChip lang="Python" />
<PlatformChip platform="TikTok" />
Level: Beginner
Language: Python
Platform: TikTok

Last Updated Chip

You can use the LastUpdatedByChip component to display information about the last update of the article. The component has the following properties:

  • authorOriginal: The original author of the article
  • createdOn: The date the article was created
  • authorLastUpdate: The author of the last update
  • updatedOn: The date of the last update

If you leave out the authorLastUpdate and updatedOn properties, the component will only display the original author and creation date.

<LastUpdatedByChip 
authorOriginal="Clara Ruthardt"
createdOn="30.09.2024"
authorLastUpdate="Cathleen Berger"
updatedOn="06.12.2024"
/>

Result:

Original post on 30.09.2024 by Clara Ruthardt
last updated on 06.12.2024 by Cathleen Berger

Create new React components

MDX can make your documentation more interactive and allows using any React components inside Markdown:

export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '20px',
color: '#fff',
padding: '10px',
cursor: 'pointer',
}}
onClick={() => {
alert(`You clicked the color ${color} with label ${children}`)
}}>
{children}
</span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !

This is Docusaurus green !

This is Facebook blue !