Skip to main content

Use Quarto to generate Docusaurus markdown

· 4 min read

This blog post shows how to use Quarto to generate Docusaurus markdown.

Quarto supports generating Docusaurus markdown files, which make it easy to create and manage Docusaurus sites.

I assume you have already installed Quarto. If not, please refer to the Get Started.

Also, I assume you have already created a Docusaurus site. If not, please refer to the Docusaurus documentation.

Quarto render all .qmd and .ipynb files in the project.

quarto render

Create Quarto project configuration

Create a _quarto.yml file in the root of your Docusaurus project.

project:
type: docusaurus

format:
docusaurus-md:
code-fold: true
html-math-method: katex

execute:
warning: false

bibliography: references.bib

Create Hygen template

Like the previous blog post, we can use Hygen to create a template for generating Docusaurus markdown files.

Create a _templates/quarto/new/index.ejs file in the root of your Docusaurus project.

---
to: blog/<%= date %>-<%= slug %>.qmd
---
---
slug: <%= slug %>
title: <%= name %>
date: <%= date %>
authors: [author]
description: A brief description
tags: [blog, other_tags]
---

Content goes here... Add your blog post text.

and a _templates/quarto/new/prompt.js file in the root of your Docusaurus project.

const today = new Date().toISOString().split('T')[0]; // Gets the current date in YYYY-MM-DD format

module.exports = [
{
type: 'input',
name: 'name',
message: 'What is the name of the blog post?',
validate: input => input ? true : 'Blog post name cannot be empty.' // Ensure input is not empty
},
{
type: 'input',
name: 'slug',
message: 'Enter a URL slug for the blog post:',
default: (answers) => {
console.log("Creating slug from:", answers.name); // Ensure 'name' is logged
return answers.name.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]+/g, '');
},
validate: input => input ? true : 'Slug cannot be empty.' // Validate slug is not empty
},
{
type: 'input',
name: 'date',
message: 'Date for the blog post (YYYY-MM-DD):',
default: today // Sets the default value to today’s date
}
];

Create a new Quarto blog post

Run the following command to create a new Quarto blog post.

hygen quarto new

✔ What is the name of the blog post? · test
✔ Enter a URL slug for the blog post: · test
✔ Date for the blog post (YYYY-MM-DD): · 2024-06-05

Loaded templates: _templates
added: blog/2024-06-05-test.qmd

The new Quarto blog post will be created in the blog directory.

You can add the following content to the blog/2024-06-05-test.qmd file.

```{python filename="hello.py"}
print(1 + 1)
```

```{r filename="hello.R"}
a <- 1
b <- 2
a + b
```



```{=mdx}
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);

<Highlight color="#25c2a0">Docusaurus GREEN</Highlight> and <Highlight color="#1877F2">Rams blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!
```

Render the Quarto blog post

Run the following command to render the Quarto blog post. If you have code chunks in the blog post, you can add the --execute flag to execute the code chunks.

quarto render [--execute]

The Quarto blog post will be rendered to the blog/2024-06-05-test.mdx file and can be viewed in your Docusaurus site.

It will be rendered as follows:

---
slug: testtest
title: testtest
date: 2024-06-05T00:00:00.000Z
authors:
- author
description: A brief description
tags:
- blog
- other_tags
---




<details class="code-fold">
<summary>Code</summary>

```python title="hello.py"
print(1 + 1)
```

</details>

``` text
2
```

<details class="code-fold">
<summary>Code</summary>

```r title="hello.R"
a <- 1
b <- 2
a + b
```

</details>

``` text
[1] 3
```

export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);

<Highlight color="#25c2a0">Docusaurus GREEN</Highlight> and <Highlight color="#1877F2">Rams blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!

Preview