Rootstock Developer Portal

This repo contains the Rootstock Developer Portal. The Developer Docs is the home for Rootstock documentation for end users and developers. Check out our quickstarts, tutorials, API reference, and code examples.

Start your journey to building dApps on Rootstock, see the Quick Start Guide or see the setup instructions, or the contributing guide for how to contribute to Rootstock Documentation.

🚀 Send us feedback

🚀 Join the global Rootstock community on Discord

This website is built using Docusaurus, a modern static website generator. For more information on how to use Docusaurus, please refer to the Docusaurus Documentation.

Requirements

Node 18+

Installation and development

Set Up

Clone this repository, and run the following commands in the root directory:

Local Development

yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Usage

Production Build

yarn build

This command generates static content into the build directory and also detects broken links.

Project Structure

The structure of this website is based on the docs folder. This structure allows for a scalable and organized website, where new sections can be easily added by creating new directories in the docs folder. Each directory within the docs folder represents a separate section on the website. This allows for a clear and organized structure, making it easy for users to navigate through the different sections of the website.

Here's a simplified example of how it might look:

/docs
  /guide
    index.md
    doc1.md
    doc2.md
  /tutorial
    index.md
    doc3.md
    doc4.md

Main Navigation and Sidebars

The main navigation of the website is created based on the root directories in the /docs folder. Each directory has its own sidebar for easy navigation.

Root directories name must contain only a character that is a letter, a number, a dash, or an underscore. If it doesn't, the directory is ignored and won't appear in main navigation.

In this case, the main navigation of the website would have two sections: "Guide" and "Tutorial".

Sidebars are created automatically based on the root directories in the /docs folder. Each section would have its own sidebar with links to the documents within that section. For example, the "Guide" section would have a sidebar with links to /guide, /guide/doc1 and /guide/doc2.

Titles of the links in the sidebar are determined by the Markdown front matter of the corresponding documents. See Style Guide

Images Storage

Images used in this project should be stored in the /static/img directory. This directory is accessible from anywhere in the project, allowing you to easily reference images in your Markdown files, JavaScript files, or CSS files.

Please note that the path to the image is relative to the root of the project, not the location of the Markdown file. This means that you should always start the path with /img/, regardless of where the Markdown file is located.

For more information on how to use images in Docusaurus, please refer to the Contributing Docs.

Writing original documentation

Steps:

Locate the docs folder
Create a markdown file in the section you wish to add the docs.
Add title, sidebar_label, tags, description, and sidebar_position attributes to the front matter as appropriate - see below for more details.
If the new page is within a collection, and it is named index.md, add a section_title, menu_title. Ensure that you set a permalink attribute in the front matter, with a trailing /.

Each documentation file should start with a Markdown front matter. This is a base set of metadata about the file, and it's written at the top of the file enclosed between two lines of three dashes. Here is a basic example for file /docs/concepts/architecture/index.md:

---
title: Run Ethereum dApps with Bitcoin Network Security
description: "The Rootstock virtual machine is compatible with Ethereum Virtual machine at an opcode level."
sidebar_label: Architecture
sidebar_position: 1
---

In this case, "Architecture" would be the title of the link in the sidebar, and the link would lead to /concepts/architecture.

The base Markdown front matter includes the following fields:

title: The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title.
description: A brief description of the document. This is optional and is not displayed in the sidebar. The description of your document, which will become the <meta name="description" content="..."/> and <meta property="og:description" content="..."/> in <head>, used by search engines.
sidebar_label: The label of the document in the sidebar. If this is not provided, the title will be used.
sidebar_position: The position of the document in the sidebar. Documents with lower numbers appear first. If this is not provided, the documents will be ordered alphabetically.

For details for Doc Creation, please refer to the Style Guide.

For a detailed description of each field, please refer to the Docusaurus Documentation.

Moving existing documentation

This applies when you have documentation already published on the devportal, but wish to move or rename it. All redirects are handled using vercel.json file.

Do not use git mv to move/ rename the file
Instead create a new file in the target location/ file path, and leave the previous one there.
In the new file, copy all the contents from the previous file, add previous and new path urls to vercel.json.

Why: This is done because when a page is published at a certain URL, that URL may be linked to externally. By renaming/ moving a page, the URL changes, and any external links may get a "404 Page Not Found" error. In this scenario, a redirect is preferred as it is much more user friendly, and search engine friendly.

Links

When adding links, prefer absolute links - e.g. links beginning with /, over relative links - e.g. links beginning with ./ or ../
Run yarn build to identify any broken links - this includes both links to other pages within devportal, and links to anchor references within devportal pages, however does not include links to external pages (not within devportal).

Broken Link Detection

This runs tests that check whether there are any errors in the site. Uses Docusaurus provides built-in broken link detection to ensure the quality of documentation. This feature is enabled by default and can be configured in the docusaurus.config.js file.

yarn build

The broken links detection is only available for both local and production builds (docusaurus build).

Here's an example of how it might look:

module.exports = {
  // ...
  onBrokenLinks: 'warn', // or 'throw', 'ignore'
  onBrokenMarkdownLinks: 'warn', // or 'throw', 'ignore'
  // ...
};

By default, it set to warn: Docusaurus will log a warning in the console, but the build will continue.

For more details on broken link detection in Docusaurus, please refer to the Docusaurus Documentation.

Findability

When you add new documentation, you should check that a visitor is able to find it through both the navigation bar, and the search functionality. The Algolia and Mendable AI Search component regularly crawls and updates content.

Search results

A reader may find your new pages through the Algolia search feature and Mendable ASK AI.
To maximize the quality of the search results, ensure that you add all of the following to the front matter for each new page
- title: This is the title of the page which is also displayed to the reader. Avoid using special characters, unicode characters, or emoji, as readers are less likely to use these in search.
- sidebar_label: The menu title appears in the navigation menu, ensure to add this on each page for easy navigation.
- sidebar_position: The position of the content on the side navigation.
- tags: Use this to set the categories, labels, or other keywords which you think a reader would search for when looking for this page.
  - Use only relevant tags. See Style Guide for how to use tags.
- description: If this is not present, it defaults to the first 200 words in the content. It is a good idea to set this to include any words or phrases which you think a reader would search for when looking for this page.

Changelog

A changelog i

Devportal

Install / Use

README