Guide: How to format content using Markdown

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)

Links

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.

:::

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.

:::

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

:::

My hub note

lorem ipsum dolor sit amet

About Note example

:::about[ My About note]

lorem ipsum dolor sit amet

:::

My About note

lorem ipsum dolor sit amet

Contribute Note example

:::contribute[ Contribute Note ]

lorem ipsum dolor sit amet

:::

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
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt

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

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

Safe-Data-Storage
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt

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

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

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

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/"
/>

Open Knowledge Foundation

OKFN

Website LinkedIn

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!

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 !

Front Matter​

Links​

Images​

Code Blocks​

Admonitions (NEW)​

Community note

Contact note

My hub note

My About note

Contribute Note

Expandable Sections (NEW)​

Icon Lists (NEW)​

Custom components (NEW)​

Author Card​

Article Card​

Chips​

Last Updated Chip​

Create new React components​

Front Matter

Links

Images

Code Blocks

Admonitions (NEW)

Expandable Sections (NEW)

Icon Lists (NEW)

Custom components (NEW)

Author Card

Article Card

Chips

Last Updated Chip

Create new React components