Skip to main content

Creating new docs

This page contains information regarding how to quickly spin up your Docusaurus documentation.

To avoid duplication, Docusaurus documentation will not be rewritten in this repo. Instead, these docs will provide more specific details for the deployment, maintenance, and development of Docusaurus in a manner consistent with the "ConsenSys Way".

Requirements
  • Ensure that you have permissions in the ConsenSys GitHub to create a new repository If you don't, write to the ConsenSys Help Desk, which administers the GitHub organization.
  • Have had a brief look at the Docusaurus documentation
  • Familiarity with Markdown syntax, specifically MDX
  • General understanding of JavaScript and React.js

Walkthrough​

  1. Proceed to this repo. You can also click on the GitHub icon on the top-right of the navbar.

  2. Click on the green "Use this template" button and on the drop-down "Create a new repository".

    See example
    useThisTemplate

  3. Fill out the details for your fork from the template. Please prefix the repo with docs- and then include your project name. For example, docs-metamask or docs-infura.

    See example
    createNewRepository

  4. Choose Public, Internal or Private depending on your needs. The difference between Internal and Private is that by default any ConsenSys member can see your repository if set as Internal, whereas Private will be completely invisible except to GitHub administrators of the organization. Consider carefully how public you want your docs to be.

  5. After creating the repository, navigate to the Settings page which is on the far right side of the <> Code tab.

  6. Ensure that the following settings are enabled/disabled from top to bottom for the General tab.

    General

    • ❌ Template repository

    Features

    • ❌ Wikis
    • ✅ Issues
    • ✅ Allow forking
    • ❌ Sponsorships
    • ❌ / ✅ Discussions
    • ❌ / ✅ Projects

    Pull Requests

    • ❌ Allow merge commits
    • ✅ Allow squash merging
    • ❌ Allow rebase merging commits
    • ❌ / ✅ Always suggest updating pull request branches
    • ❌ Allow auto-merge
    • ✅ Automatically delete head branches

  7. Go to the Collaborators and teams under Access on the left sidebar. Add protocol-pliny from the green Add teams button. Add any other relevant teams, such as your own as needed.

  8. At the moment, it is not possible to easily use branch protection on main when using the semantic-release plugin. If you disable this, then branch protection can be enabled.

Running locally​

You will need to have Node.js installed to run the live previews of the docs locally.

It is highly recommended that you use a tool like nvm to manage Node.js versions on your machine.

  1. Follow the above instructions to install nvm on your machine, or go here.
  2. Go to root folder of this project in your terminal.
  3. Run nvm install followed by nvm use. This will install the version specified by this project in the .nvmrc file.

Running this project​

  1. Navigate to root folder of the project after installing Node.js

  2. Run the following in sequence, which only needs to be done once:

    npm install
    npm run prepare

  3. To preview and for every time afterwards:

    npm run start