Starknet documentation repository

Table of Contents

• Contributing to Starknet documentation
• Different ways to contribute
• Tips on authoring
• Before you begin
• Building and previewing content locally
• Releasing Starknet docs on GitHub (for Admins only)

The Starknet docs website, https://docs.starknet.io, is written in AsciiDoc and is built using Antora, a static website generator for AsciiDoc.

Contributing to Starknet documentation

If you are interested in contributing to Starknet technical documentation, the following table provides quick links to help you get started.

Question	Resource
I’m interested, how do I contribute?	For information on how you can contribute, see Different ways to contribute.
Are there any basic guidelines to help me?	For basic guidelines to help us keep our content consistent, see Documentation guidelines.
Is there a style guide and writing guide I should use?	See the Starknet documentation supplementary style guide.
How do I set up my workstation?	See Setting up your environment.

Different ways to contribute

There are a few different ways you can contribute to Starknet documentation:

• Create a GitHub issue.

• Submit a pull request (PR). You can create a local clone of your own fork of the starknet-docs repository, make your changes, and submit a PR. This option is best if you have substantial changes, or to help the changes you want to be added more quickly.

What happens when you submit a PR?

When you submit a PR, the Starknet Docs team reviews the PR and arranges further technical reviews as necessary. If the PR requires changes, the reviewers add comments to the PR. We might request that you make the changes, or let you know that we incorporated your content in a different PR. Occasionally, we might add commits to the original PR directly. When the PR has been reviewed and all updates are complete, the documentation team merges the PR and applies it to the valid version(s).

Tips on authoring

• Starknet documentation supplementary style guide: General style guidance and writing guidance.

For information on writing in AsciiDoc, see:

• AsciiDoc Language Documentation

• AsciiDoc Syntax Quick Reference

Note

There are multiple ways of coding ids, source code blocks, cross-references, and links. In general we use the most explicit coding conventions for coding in order to prioritize code readability. Most of these coding conventions are listed in AsciiDoc Mark-up Quick Reference for Red Hat Documentation

Before you begin

1. Install yarn if it’s not already installed.

2. Install npx if it’s not already installed.

3. Clone this repo, either from a fork, or if you are an official collaborator, then directly from starknet-io/starknet-docs.

4. Change to the starknet-docs directory.

5. Run the yarn command to prepare the environment:

   yarn

yarn should prepare your environment by installing the required modules based on package-lock.json and package.json. If it was successful, you should be able to build and preview content.

Building and previewing content locally

After writing or editing content, to preview your changes:

1. Build the content by running the build_local_site.sh build script:

   $ ./build_local_site

   This command generates the website in the directory public_html.

2. Open the website by doing one of the following:

   • Open the start page: <repo_root>/public_html/index.html.

   • Run the http server packaged with Antora:

     $ npx http-server public_html -c-1

     The server runs, and gives you one or more local URLs that you can use to view the website. For example:

     Starting up http-server, serving public_html
     
     ...
     
     Available on:
       http://127.0.0.1:8080
       http://192.168.68.111:8080
       http://192.168.14.3:8080
       http://10.14.0.2:8080
     Hit CTRL-C to stop the server

Releasing Starknet docs on GitHub (for Admins only)

The high-level process for releasing documentation changes in this repository.

During the course of content development, writers merge branches with changes either directly into main, into a secondary branch as needed, where these changes wait until we are ready to release them—that is, post them to docs.starknet.io.

GitHub actions create Git tags and releases that appear at the repo’s Releases and Tags pages.

When a feature branch is merged into the main branch, a GitHub action creates a release tag in the format v<version>.<major_update>.<minor_update> and updates CHANGELOG.md. It then publishes the new content to docs.starknet.io.

Procedure

Merging a feature branch to main automatically publishes changes in the feature branch. No additional steps are required.

GitHub increments the version numbers in package.json and package-lock.json, and updates CHANGELOG.md with the descriptions of each PR that was just merged into main. . Update your local main branch from the remote main branch using one of the following:

• Pull the changes:

  starknet-docs (main) git pull

• Do a rebase from [email protected]:starknet-io/starknet-docs.git:

  starknet-docs (main) git fetch origin
  starknet-docs (main) git rebase origin/main

  Note	If you are using a fork, then your forked repo is origin by default, in which case you should assign the name upstream to [email protected]:starknet-io/starknet-docs.git. So when rebasing, use upstream instead of origin in the above commands.