You can press ctrl+c
to quit the development server.
Deploying a documentation website with Docusaurus on Scaleway
- docusaurus
- cms
- github
Docusaurus is an open-source documentation framework. It allows you to build, deploy, and maintain documentation websites. It comes with features such as blogs, internationalization, search, and versioning.
It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. The tool is a static-site generator and provides out-of-the-box documentation features - but can be used to create any kind of static website (personal website, product, blog, marketing landing pages, etc.).
Before you start
To complete the actions presented below, you must have:
- A Scaleway account logged into the console
- Owner status or IAM permissions allowing you to perform actions in the intended Organization
- An Object Storage bucket with the bucket website feature enabled
- A GitHub account and an empty repository for your Project
- A local development environment with Node.js (version 16.14 or above) and
git
installed
Generating a new site
Docusaurus is available for most operating systems. In this tutorial, we describe the installation on an Ubuntu Linux system. For other operating systems, refer to the official documentation.
- Open a terminal on your computer.
- Type the following command in the terminal to generate a new Docusaurus site:
You will be prompted to install the latestnpx create-docusaurus@latest
create-docusaurus
package (here 3.4.0). Typey
to proceed.Once the installation is complete, you will be prompted to provide some information about your new documentation website:Need to install the following packages:create-docusaurus@3.4.0Ok to proceed? (y) y- A name for your new site (for example:
docusaurus-on-scaleway
) - A template for your website (for example:
classic (recommended)
) - Confirm that you want to use the TypeScript version of the template by typing
y
.
Docusaurus will create the new site and all related files.✔ What should we name this site? … docusaurus-on-scaleway✔ Select a template below... › classic (recommended)✔ This template is available in TypeScript. Do you want to use the TS variant? … yes - A name for your new site (for example:
- Enter the directory of your new site:
You can see that Docusaurus created several files and directories:cd docusaurus-on-scalewaylsREADME.md docusaurus.config.js sidebars.jsbabel.config.js node_modules srcblog package-lock.json staticdocs package.json tsconfig.json
- Deploy a preview of your site using the development web server by running the following command:
Your browser opens a new tab automatically, pointing tonpm start
http://localhost:3000
, and displaying the Docusaurus site.Tip - Run the following command to initialize a new git repository inside the Docusaurus website folder on your local computer:
git init
- Configure a remote upstream of your repository, pointing to your GitHub repository:
git remote add origin git@github.com:<YOUR_GITHUB_USER>/<YOUR_GITHUB_REPOSITORY_NAME>.gitTip
If you have no GitHub repository yet, create a new one from the web interface or via the GitHub CLI by running the following command:
gh repo create <YOUR_GITHUB_REPOSITORY_NAME> --private - Add the Docusaurus files to your repository, commit, and push the changes:
git add .git commit -m "Initial commit"git push -u origin main
Deploying to Scaleway Object Storage
You must configure an Object Storage bucket with the bucket website feature enabled before you continue.
- Open a web browser and go to your project’s repository on GitHub.com.
- Click the Settings tab to display the settings of your repository.
- Click Secrets > Actions in the side menu. A list of the Actions’ secrets displays. GitHub Secrets are encrypted data of sensitive information. They are used here to store the Scaleway secret key and access key.
- Click New repository secret to create a new secret. Name it
SCW_ACCESS_KEY_ID
and enter your access key as secret value. - Click Add secret to save your configuration.
- Repeat the step above with a secret named
SCW_SECRET_ACCESS_KEY
and your secret key as secret value. - Repeat the step above again and set a secret named
SCW_S3_BUCKET
and your bucket name as secret value. - Click the Actions tab. A list of suggested GitHub Actions for your project displays.
- Click Skip this and set up a workflow yourself.
- Copy the following code in the text editor, keep the default file name
main.yml
and click Start commit:name: Deploy Docusaurus to S3on:push:branches:- mainjobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- uses: bene2k1/s3-docusaurus-sync-action@mainenv:SCW_BUCKET_REGION: "fr-par"# Set this to the region corresponding to the geographical location of your bucketSCW_S3_BUCKET: ${{ secrets.SCW_S3_BUCKET }}SCW_ACCESS_KEY_ID: ${{ secrets.SCW_ACCESS_KEY_ID }}SCW_SECRET_ACCESS_KEY: ${{ secrets.SCW_SECRET_ACCESS_KEY }}NoteThe GitHub Action used to deploy the Docusaurus site on Scaleway Object Storage is forked from turnerlabs/s3-docusaurus-sync-action.
- Enter a commit message, select Commit directly to the
main
branch and click Commit new file.
The runner runs automatically for the first time and builds and deploys your documentation website to the Object Storage bucket.
Adding more pages
You can add several types of content to your Docusaurus site:
Refer to the official documentation for more information about the different types of content.
Once you have created your content, add it to your working tree, then commit and push it to your GitHub repository:
git add .git commit -m "More content commit"git push -u origin main
The GitHub runner will run Docusaurus and build your website. It will then deploy it on your Scaleway Object Storage.
Conclusion
Docusaurus is now set up to rebuild your site every time you push new content to the main
branch of your GitHub repository. Docusaurus then deploys it automatically on your Object Storage website.
All changes go live on your website as soon as the GitHub runner has completed its tasks and the build of your website is completed successfully.
For more information about Docusaurus, refer to the official documentation. An alternative solution to Docusaurus is Hugo, which provides similar features.