---
id: create-doc
title: Create a doc
description: Create a Markdown Document
slug: /create-doc
---

Create a Markdown file, `greeting.md`, and place it under the `docs` directory.

```bash
website # root directory of your site
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...
```

At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.

```yml
---
id: greeting
title: Hello
---

## Hello from Docusaurus

Are you ready to create the documentation site for your open source project?

### Headers

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

### Only h2 and h3 will be in the toc by default.

You can configure the TOC heading levels either per-document or in the theme configuration.

The headers are well-spaced so that the hierarchy is clear.

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times

### Custom id headers {#custom-id}

With `{#custom-id}` syntax you can set your own header id.
```

This will render in the browser as follows:

```mdx-code-block
import BrowserWindow from '@site/src/components/BrowserWindow';

<BrowserWindow url="http://localhost:3000">

<h2>Hello from Docusaurus</h2>

Are you ready to create the documentation site for your open source project?

<h3>Headers</h3>

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

<h3>Only h2 and h3 will be in the toc by default.</h3>

You can configure the TOC heading levels either per-document or in the theme configuration.

The headers are well-spaced so that the hierarchy is clear.

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times

<h3 id="custom-id">Custom id headers</h3>

With <code>{#custom-id}</code> syntax you can set your own header id.

</BrowserWindow>
```

:::note

All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default.

Read more about [importing partial pages](../markdown-features/markdown-features-react.mdx#importing-markdown).

:::

## Doc tags {#doc-tags}

Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar.md). Tags are passed in the front matter as a list of labels:

```yml "your-doc-page.md"
---
id: doc-with-tags
title: A doc with tags
tags:
  - Demo
  - Getting started
---
```

:::tip

Tags can also be declared with `tags [Demo, Getting started]`

Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).

:::