Scaffold-Stylus Docs

This website contains Scaffold-Stylus Documentation and is built using Docusaurus 2.

Requirements

To run the Documentation site locally, but first ensure you have Node and Git installed.

Installation

Clone the repository, install all dependencies as well as build all local packages, and then start Docusaurus.

git clone https://github.com/Arb-Stylus/scaffold-stylus-docs.git
cd scaffold-stylus-docs
npm install
npm run start

Run docs with search feature enabled

Instead of npm run start, you'll need to:

npm run docusaurus build
npm run docusaurus serve

If you change the search configuration, you'll need to run npm run docusaurus build and then npm run docusaurus serve again to refresh with the changes.

Deploy to github page

Follow this doc to config your docusaurus.config.js Then run

USE_SSH=true npm run deploy

Note You need to config your SSH key before deploying

Contribution Guidelines

Thank you for your interest in contributing to improve the documentation!

There are two types of contributions you can make:

• Fix errors or add new pages to the current documentation content.
• Fix bugs or introduce new features to the documentation website (within the Docusaurus codebase).

Content contributions

The documentation content is written in Markdown format and is located in the docs folder. If you’re not familiar with Markdown, please check this guide or this cheat sheet to get started.

MDX files are also present, they combine Markdown with React. You can learn more about MDX files in Docusaurus docs.

Existing content

If you find anything that is confusing or can be improved in an existing document, you can click "Edit this page" at the bottom of the page, which will redirect to the GitHub edit form of that document. Make your changes and submit a pull request (PR).

New content

When adding a new page, you need to fork the repository, create a new branch, and make all changes necessary in your repository. Once you are done with your changes, create a PR to Scaffold-Stylus Documentation repository.

Add the new pages to the docs folder, placing them in the specific directory where you want the page to be shown. Sidebar link will get autogenerated under your specific folder, in the position that you specify in your document header. Example:

---
sidebar_position: 2
---

If you want to create a new folder to the Document structure, you'll need to add the new folder and a markdown document with the same name of that folder, which will be displayed when the users click on the sidebar link.

Images and Media

To add images to your documentation:

1. Place images in the static/img/ directory - All static assets should be placed in the static folder, which gets served at the root URL.

2. Reference images in your markdown - Use standard markdown image syntax:

   ![Alt text](/img/your-image.png)

   The /img/ path corresponds to the static/img/ directory in your project.

3. Supported formats - Docusaurus supports common image formats like PNG, JPG, JPEG, GIF, and SVG.

4. Example usage - Here's how images are currently used in the docs:

   ![Balance Example](/img/Balance.gif)
   ![AddressInput Example](/img/addressInput.gif)

5. Best practices:

   • Use descriptive alt text for accessibility
   • Optimize images for web (compress large files)
   • Use GIFs for demonstrating interactions
   • Use PNG for screenshots and diagrams
   • Use SVG for icons and simple graphics

Category Configuration

The _category_.json files are used to configure how folders appear in the Docusaurus sidebar. Each folder in your docs directory can have a _category_.json file to customize its appearance and behavior.

Purpose of _category_.json:

• Define the label (display name) for the folder in the sidebar
• Set the position/order of the folder in the sidebar
• Configure the generated index page for the folder
• Add descriptions and metadata

Example _category_.json structure:

{
  "label": "⚙ Components",
  "position": 3,
  "link": {
    "type": "generated-index",
    "slug": "components",
    "description": "Scaffold-Stylus provides a set of pre-built components for common web3 use cases."
  }
}

Key properties:

• label: The display name in the sidebar (can include emojis)
• position: Numeric order in the sidebar (lower numbers appear first)
• link.type: Set to "generated-index" to create an overview page
• link.slug: URL slug for the category page
• link.description: Description shown on the generated index page

When to create a _category_.json file:

• When you want to customize how a folder appears in the sidebar
• When you want to add a description or change the folder name
• When you want to control the order of folders in the sidebar
• When you want to create a generated index page for a folder

Current examples in this project:

• docs/components/_category_.json - Creates "⚙ Components" section
• docs/deploying/_category_.json - Creates "🛳 Shipping Your dApp" section
• docs/recipes/_category_.json - Creates "🧪 Recipes" section

Website contributions

For contributions to the Website Code, we follow the "fork-and-pull" Git workflow.

Fork the repository, create a new branch, and make all changes necessary in your repository. Once you are done with your changes, create a PR to Scaffold-Stylus Documentation repository.

Configuration

• docusaurus.config.js - This file contains the Docusaurus configuration. Here you can manage site metadata, links in the header and footer, and theme configuration. You can visit Docusaurus docs to learn more about the Docusaurus settings.

Sidebars

• sidebars.js - This specifies the sidebars for your documentation. You'll see that we currently have type: 'autogenerated' configured for the sidebar. This will generate sidebar menu links based on the folder structure and positions defined in each document.

  The full documentation for this file is available on the Docusaurus website.

Styles

• src/css/custom.css - This file contains our custom modifications on top of the Docusaurus 'classic' theme. For in-depth understanding of Docusaurus Styling and Layout you can visit their docs, where you will find the Theme Class Names in order to modify them in our custom.css.

If there's something overlooked in this README.md or if any instructions are unclear, remember you can also contribute to improve it. Fork, modify and PR to our repository!

All contributions are welcome!