Starknet documentation repository

Table of Contents

• Contributing to Starknet documentation
• Different ways to contribute
• Tips on authoring
• Building and previewing content locally
• Releasing Starknet docs on Github

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 in 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

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:

     $ 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

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

During the course of content development, writers merge branches with changes into dev, 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 the dev branch is merged into the master branch, a github action creates a tag and release, and updates CHANGELOG.md.

Note	Previously, this repo used Pre-release tags in addition to Release tags. This functionality is useful for application development, which requires validating multiple release candidates. This usage model does not typically apply to documentation.

Procedure

1. Checkout the master branch.

2. Fetch the latest changes from the main repo, origin. If your origin is a fork of the main repo, update this command appropriately:

   starknet-docs (master) $ git fetch origin

3. Merge dev into master on your local starknet-docs repo:

   starknet-docs (master) $ git merge origin/dev

   Your local version of master now includes all the changes from the remove version of dev.

4. Push the local version of master to Github:

   starknet-docs (master) $ git push origin master

   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 master.

5. Update your local dev branch from the remote master branch:

   starknet-docs (master) $ git checkout dev
   starknet-docs (dev) $ git fetch origin
   starknet-docs (dev) $ git rebase origin/master
   starknet-docs (dev) $ git push origin dev