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:
---
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.
function HelloDocusaurus() {
return (
<h1>Hello, Docusaurus!</h1>
)
}
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 titletitle
: The title of the itemicon
: The path to the icon that is displayed. The icons are stored in thestatic/img/icons
folder.blob
: The path to the blob that is displayed. There are 7 different blue blobs and 4 green blobs available in thestatic/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
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 authoravatarSrc
: The path to the avatar of the authorposition
: The position of the authorwebsite
: The website of the authorlinkedin
: The LinkedIn profile of the authortwitter
: The Twitter / X profile of the authormastodon
: The GitHub profile of the authorscholar
: 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 articleauthor
: The author of the articleteaser
: A short teaser text about the articlelink
: The link to the articleorganization
: 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"
/>
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" />
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 articlecreatedOn
: The date the article was createdauthorLastUpdate
: The author of the last updateupdatedOn
: 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:
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 !