Dinosaurs are cooler without a web server!
Docusaurus-Static is just a set of independent postprocessing and runtime scripts, that can complement an existing standard Docusaurus site. Just 1 instantaneous build step and a couple of static files will make you achieve maximum web compatibility.
You focus on your content, Docusaurus takes care of all the rendering chores, and Docusaurus-Static makes the website work good in all serverless situations. Go ahead and move your docs into the docs directory, or start writing in blog.
Docusaurus-Static keeps the full functionality of Docusaurus available for server deployments, letting you extend or customize your website layout by reusing React, while allowing basic functionality to still work without any heavy framework.
You don't need React to write simple standalone pages.
This site, built with Docusaurus, doubles both as the demo for Docusaurus-Static, and new sites created with it, as well as a guide and documentation specific to Docusaurus-Static. Use the navigation menu to get to all the information. Also, check out the blog.
5 minutes to learn the most important Docusaurus concepts.
Add Markdown or React files to src/pages to create a standalone page:
Documents are groups of pages connected through:
Docusaurus creates a page for each blog post, but also a blog index page, a tag system, an RSS feed...
Docusaurus supports Markdown and a few additional features.
Docusaurus is a static-site-generator (also called Jamstack).
You have just learned the basics of Docusaurus and made some changes to the initial template.
This proof-of-concept wouldn't have been possible without...
postprocess.js script, by @ohkimur, from which my docusaurus-static-postprocess.js script is derived.If you're a beginner to all of this, don't have many requirements, or don't already have a prior Docusaurus usage, it's recommended that you follow this immediate setup to get started.
First, download and unpack the latest source archive for this exact site from https://gitlab.com/octospacc/editocttrialTools/-/archive/main/editocttrialTools-main.zip?path=docusaurus-static.
Only for the first time, run npm install in the main extracted directory, to install all needed dependencies.
You can now run your site in development mode with npm run start, just like with standard Docusaurus. Edit files in /docs/ or /blog/ to test out everything or to write your real content, and watch changes being rendered.
Anytime you want to create an actual static build of the site, good for both remote deployment and local usage, run npm run build+postprocess. You will find your output in the /build/ directory by default.
(To be finished)
In short, download the following files from the source repo and place them in the respective paths of your existing Docusaurus site:
docusaurus-static-postprocess.jssrc/docusaurus-static/single-file.htmlstatic/docusaurus-static.cssstatic/docusaurus-static.jsThen, add these lines to the to of the scripts section of your existing package.json file:
"postprocess": "echo Postprocessing... && node ./docusaurus-static-postprocess.js && echo Done!",
"build+postprocess": "docusaurus build && npm run postprocess",
Now you can build your Docusaurus-Static site with npm run build+postprocess.
Add Markdown or React files to src/pages to create a standalone page:
src/pages/index.js → localhost:3000/src/pages/foo.md → localhost:3000/foosrc/pages/foo/bar.js → localhost:3000/foo/barCreate a file at src/pages/my-react-page.js:
import React from 'react';
import Layout from '@theme/Layout';
export default function MyReactPage() {
return (
<Layout>
<h1>My React page</h1>
<p>This is a React page</p>
</Layout>
);
}
A new page is now available at http://localhost:3000/my-react-page.
Create a file at src/pages/my-markdown-page.md:
# My Markdown page
This is a Markdown page
A new page is now available at http://localhost:3000/my-markdown-page.
Documents are groups of pages connected through:
Create a Markdown file at docs/hello.md:
# Hello
This is my **first Docusaurus document**!
A new document is now available at http://localhost:3000/docs/hello.
Docusaurus automatically creates a sidebar from the docs folder.
Add metadata to customize the sidebar label and position:
---
sidebar_label: 'Hi!'
sidebar_position: 3
---
# Hello
This is my **first Docusaurus document**!
It is also possible to create your sidebar explicitly in sidebars.js:
export default {
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
};
Docusaurus is a static-site-generator (also called Jamstack).
It builds your site as simple static HTML, JavaScript and CSS files.
Build your site for production:
npm run build
The static files are generated in the build folder.
Test your production build locally:
npm run serve
The build folder is now served at http://localhost:3000/.
You can now deploy the build folder almost anywhere easily, for free or very small cost (read the Deployment Guide).
Docusaurus supports Markdown and a few additional features.
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)
Regular Markdown links are supported, using url paths or relative file paths.
Let's see how to [Create a page](/create-a-page).
Let's see how to [Create a page](./create-a-page.md).
Result: Let's see how to Create a page.
Regular Markdown images are supported.
You can use absolute paths to reference images in the static directory (static/img/docusaurus.png):
You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
Markdown code blocks are supported with Syntax highlighting.
```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
return <h1>Hello, Docusaurus!</h1>;
}
```
function HelloDocusaurus() {
return <h1>Hello, Docusaurus!</h1>;
}
Docusaurus has a special syntax to create admonitions and callouts:
:::tip[My tip]
Use this awesome feature option
:::
:::danger[Take care]
This action is dangerous
:::
Use this awesome feature option
This action is dangerous
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 !
For demonstrative purposes, and since everything said in it still applies, the original demo content that serves as a tutorial for Docusaurus is being left available here.
Let's discover Docusaurus in less than 5 minutes.
Get started by creating a new site.
Or try Docusaurus immediately with docusaurus.new.
Generate a new Docusaurus site using the classic template.
The classic template will automatically be added to your project after you run the command:
npm init docusaurus@latest my-website classic
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
The command also installs all necessary dependencies you need to run Docusaurus.
Run the development server:
cd my-website
npm run start
The cd command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
The npm run start command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
Open docs/intro.md (this page) and edit some lines: the site reloads automatically and displays your changes.
Docusaurus creates a page for each blog post, but also a blog index page, a tag system, an RSS feed...
Create a file at blog/2021-02-28-greetings.md:
---
slug: greetings
title: Greetings!
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tags: [greetings]
---
Congratulations, you have made your first post!
Feel free to play around and edit this post as much as you like.
A new blog post is now available at http://localhost:3000/blog/greetings.
You have just learned the basics of Docusaurus and made some changes to the initial template.
Docusaurus has much more to offer!
Have 5 more minutes? Take a look at versioning and i18n.
Anything unclear or buggy in this tutorial? Please report it!
docusaurus.config.jsthemeConfigDocusaurus can manage multiple versions of your docs.
Release a version 1.0 of your project:
npm run docusaurus docs:version 1.0
The docs folder is copied into versioned_docs/version-1.0 and versions.json is created.
Your docs now have 2 versions:
1.0 at http://localhost:3000/docs/ for the version 1.0 docscurrent at http://localhost:3000/docs/next/ for the upcoming, unreleased docsTo navigate seamlessly across versions, add a version dropdown.
Modify the docusaurus.config.js file:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
},
],
},
},
};
The docs version dropdown appears in your navbar:
It is possible to edit versioned docs in their respective folder:
versioned_docs/version-1.0/hello.md updates http://localhost:3000/docs/hellodocs/hello.md updates http://localhost:3000/docs/next/hello
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
This is the summary of a very long blog post,
Use a <!-- truncate --> comment to limit blog post size in the list view.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Blog posts support Docusaurus Markdown features, such as MDX.
Use the power of React to create interactive blog posts.
<button onClick={() => alert('button clicked!')}>Click me!</button>
Docusaurus blogging features are powered by the blog plugin.
Simply add Markdown files (or folders) to the blog directory.
Regular blog authors can be added to authors.yml.
The blog post date can be extracted from filenames, such as:
2019-05-30-welcome.md2019-05-30-welcome/index.mdA blog post folder can be convenient to co-locate blog post images:
The blog supports tags as well!
And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.
Let's translate docs/intro.md to French.
Modify docusaurus.config.js to add support for the fr locale:
export default {
i18n: {
defaultLocale: 'en',
locales: ['en', 'fr'],
},
};
Copy the docs/intro.md file to the i18n/fr folder:
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
Translate i18n/fr/docusaurus-plugin-content-docs/current/intro.md in French.
Start your site on the French locale:
npm run start -- --locale fr
Your localized site is accessible at http://localhost:3000/fr/ and the Getting Started page is translated.
In development, you can only use one locale at a time.
To navigate seamlessly across languages, add a locale dropdown.
Modify the docusaurus.config.js file:
export default {
themeConfig: {
navbar: {
items: [
{
type: 'localeDropdown',
},
],
},
},
};
The locale dropdown now appears in your navbar:
Build your site for a specific locale:
npm run build -- --locale fr
Or build your site to include all the locales at once:
npm run build
Docusaurus-Static is a set made out of a build postprocessing script, and several static runtime files, that can be used to make any Docusaurus site magically work without a web server.
Not only can the built site be navigated as a collection of static HTML pages from file:/// locations or indiscriminate domains, but is now also made to be contained in a single-file HTML application. Only if you're not already on it, try opening docusaurus-static-single-file.html...
Docusaurus blogging features are powered by the blog plugin.
Simply add Markdown files (or folders) to the blog directory.
Regular blog authors can be added to authors.yml.
The blog post date can be extracted from filenames, such as:
2019-05-30-welcome.md2019-05-30-welcome/index.mdA blog post folder can be convenient to co-locate blog post images:
The blog supports tags as well!
And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.
Blog posts support Docusaurus Markdown features, such as MDX.
Use the power of React to create interactive blog posts.
<button onClick={() => alert('button clicked!')}>Click me!</button>
This is the summary of a very long blog post,
Use a <!-- truncate --> comment to limit blog post size in the list view.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Archive
Docusaurus-Static is a set made out of a build postprocessing script, and several static runtime files, that can be used to make any Docusaurus site magically work without a web server.
Not only can the built site be navigated as a collection of static HTML pages from file:/// locations or indiscriminate domains, but is now also made to be contained in a single-file HTML application. Only if you're not already on it, try opening docusaurus-static-single-file.html...
Docusaurus blogging features are powered by the blog plugin.
Simply add Markdown files (or folders) to the blog directory.
Regular blog authors can be added to authors.yml.
The blog post date can be extracted from filenames, such as:
2019-05-30-welcome.md2019-05-30-welcome/index.mdA blog post folder can be convenient to co-locate blog post images:
The blog supports tags as well!
And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.
This is the summary of a very long blog post,
Use a <!-- truncate --> comment to limit blog post size in the list view.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Docusaurus-Static is a set made out of a build postprocessing script, and several static runtime files, that can be used to make any Docusaurus site magically work without a web server.
Not only can the built site be navigated as a collection of static HTML pages from file:/// locations or indiscriminate domains, but is now also made to be contained in a single-file HTML application. Only if you're not already on it, try opening docusaurus-static-single-file.html...
Docusaurus blogging features are powered by the blog plugin.
Simply add Markdown files (or folders) to the blog directory.
Regular blog authors can be added to authors.yml.
The blog post date can be extracted from filenames, such as:
2019-05-30-welcome.md2019-05-30-welcome/index.mdA blog post folder can be convenient to co-locate blog post images:
The blog supports tags as well!
And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.
Blog posts support Docusaurus Markdown features, such as MDX.
Use the power of React to create interactive blog posts.
<button onClick={() => alert('button clicked!')}>Click me!</button>
This is the summary of a very long blog post,
Use a <!-- truncate --> comment to limit blog post size in the list view.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Docusaurus-Static is a set made out of a build postprocessing script, and several static runtime files, that can be used to make any Docusaurus site magically work without a web server.
Not only can the built site be navigated as a collection of static HTML pages from file:/// locations or indiscriminate domains, but is now also made to be contained in a single-file HTML application. Only if you're not already on it, try opening docusaurus-static-single-file.html...
Docusaurus blogging features are powered by the blog plugin.
Simply add Markdown files (or folders) to the blog directory.
Regular blog authors can be added to authors.yml.
The blog post date can be extracted from filenames, such as:
2019-05-30-welcome.md2019-05-30-welcome/index.mdA blog post folder can be convenient to co-locate blog post images:
The blog supports tags as well!
And if you don't want a blog: just delete this directory, and use blog: false in your Docusaurus config.