Using the Tutorial Template

To get you started quickly at writing and guarantee a minimum amount of organization overhead, we created a tutorial template, that you can use as a starting point for your new tutorials. Read below to find out how to use it, adapt it, and make it visible.

Copying the Template Files

The tutorial template is located in the repository at docs/tutorial-template.

To start a new tutorial with hints and preformatted headings, go ahead and copy that folder to a new folder in the same parent directory.

Afterwards rename the folder to a name that describes your tutorial. The folder name will later also be the slug, that is displayed in a user's browser, so make it precise and short. Also only use alphanumeric keys alongside the - character.

Example

Let's say the tutorial name is How to build a OpenGOV frontend with polkadot.js, a good folder name could be opengov-with-polkadot-js.

Make sure you copy the files and do not just rename the template folder, so authors coming after you can still use a fresh template for their tutorials. You can either do it in your OS or use this command from the root of your forked repo folder:

# Copy the tutorial template to a new folder
cp -r docs/tutorial-template tutorials/your-folder-name

After you completed this step, the folder structure should e.g. look like the following

tutorials/
├── ...
├── opengov-with-polkadot-js
│   ├── 0-intro.mdx
│   ├── 1-step1.mdx
│   ├── 2-step2.mdx
│   └── 3-conclusion.mdx
├── tutorial-template
│   ├── 0-intro.mdx
│   ├── 1-step1.mdx
│   ├── 2-step2.mdx
│   └── 3-conclusion.mdx
└── ...

info

You might notice, that all filenames are prefixed with a number. That is not mandatory but helps at structuring. If you reference your files, you can omit the numbers as you can see in the next step.

When you now navigate to localhost:3000, you should see your new tutorial on the frontpage. Before you start, there is one more thing todo: sidebars.

Adding your Tutorial to the Tutorial Sidebar

After copying the tutorial template and renaming it, you want to wire it to a sidebar in order for readers to navigate your tutorial. When you click, the frontpage link to your tutorial at the moment, you will notice that it has no sidebar. Docusaurus lets us define sidebars in sidebars.js. You can create a sidebar for your tutorial with the following code:

/sidebars.js

const sidebars = {
  //...other sidebars
  yourTutorialNameSidebar: [
    "[your-folder-name]/intro",
    "[your-folder-name]/step1",
    "[your-folder-name]/step2",
    "[your-folder-name]/conclusion",
  ],

🎉 You have now successfully integrated a tutorial template with polkadot.study. Now you can go ahead to write your tutorial. Remember to update the sidebar, when you update your file structure.