DOCSEARCHbyAlgolia
Submit Docs

Docusaurus Documentation

website·Indexed 29 days ago

https://notes.chen-yu-hsin.me

A static-site generator designed for quickly setting up websites. Features include support for Markdown and React pages, a built-in blog plugin with tag systems and RSS feeds, i18n configuration for site translation, and documentation versioning.

Tokens
3.3K
Snippets
30
Records
37
Agent score
50%

What's inside Docusaurus

  1. Overview of Docusaurus core features

    Docusaurus is a React-powered static site generator designed for quick installation and deployment of documentation websites. It allows developers to focus on content by placing documentation files in the docs directory and provides the ability to extend or customize website layouts using React components while maintaining consistent global elements like headers and footers.

  2. Launch the Docusaurus development server

    After generating a site, navigate into the project directory and start the development server. This builds the website locally and serves it at http://localhost:3000/. The server supports hot-reloading, meaning changes made to files (such as docs/intro.md) will be displayed automatically without a manual refresh.
    cd my-website
npm run start

  3. Limit blog post preview size in list view

    To limit the amount of content displayed for a blog post in the list view, insert the <!-- truncate --> HTML comment at the point where the content should be cut off.
    This content will appear in the list view.

<!-- truncate -->

This content will only appear on the full post page.

  4. Update content for specific documentation versions

    Docusaurus separates versioned content from the current development content. To update a specific version, edit the files within the corresponding versioned_docs folder. To update the upcoming/unreleased version, edit files in the main docs folder.

    • Versioned docs: versioned_docs/version-1.0/hello.md $\rightarrow$ http://localhost:3000/docs/hello
    • Current/Next docs: docs/hello.md $\rightarrow$ http://localhost:3000/docs/next/hello

  5. Embed images in Docusaurus Markdown

    Images can be embedded using absolute paths (referencing the static directory) or relative paths (colocating images with Markdown files).
    # Absolute path (from static/img/)
![Docusaurus logo](/img/docusaurus.png)

# Relative path
![Docusaurus logo](./img/docusaurus.png)

  6. Create standalone pages using the src/pages directory

    To create a standalone page, add a Markdown or React file to the src/pages directory. The file system structure determines the URL path:

    • src/pages/index.js maps to the root / (e.g., localhost:3000/)
    • src/pages/foo.md maps to /foo (e.g., localhost:3000/foo)
    • src/pages/foo/bar.js maps to /foo/bar (e.g., localhost:3000/foo/bar)

  7. Create and organize blog posts in Docusaurus

    Docusaurus blogging features are powered by the @docusaurus/plugin-content-blog plugin. To create blog posts, add Markdown files or folders to the blog directory. To co-locate images with a specific post, use a folder structure where the post content is in an index.md file. Blog post dates are automatically extracted from filenames using the format YYYY-MM-DD-title.md (e.g., 2019-05-30-welcome.md).

  8. Install and initialize a new Docusaurus site

    To create a new Docusaurus site using the classic template, you must have Node.js version 18.0 or above installed. Run the initialization command in your terminal to generate the project structure and install all necessary dependencies.
    npm init docusaurus@latest my-website classic

  10. Create and organize blog posts in Docusaurus

    Docusaurus blogging features are powered by the @docusaurus/plugin-content-blog plugin. To create blog posts, add Markdown files or folders to the blog directory. You can co-locate images within a blog post folder by creating a folder for the post and placing an index.md file inside it. Blog post dates are automatically extracted from filenames using the format YYYY-MM-DD-title.md (e.g., 2019-05-30-welcome.md).

  11. Add syntax-highlighted code blocks with titles

    Docusaurus supports Markdown code blocks with syntax highlighting. You can optionally add a title to the code block to indicate the filename or purpose.
    ```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}

  12. Use React components in Markdown via MDX

    Docusaurus supports MDX, allowing you to export and use React components directly within your Markdown files to create interactive content.
    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> !