The Starknet docs website, https://docs.starknet.io, is written in AsciiDoc and is built using Antora, a static website generator for AsciiDoc.
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? |
|
How do I set up my workstation? |
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).
-
Starknet documentation supplementary style guide: General style guidance and writing guidance.
For information on writing in AsciiDoc, see:
|
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 |
After writing or editing content, to preview your changes:
-
Build the content by running the
build_local_site.shbuild script:$ ./build_local_site
This command generates the website in the directory
public_html. -
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
-
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.
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. |
-
Checkout the
masterbranch. -
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
-
Merge
devintomasteron your local starknet-docs repo:starknet-docs (master) $ git merge dev
Your local version of
masternow includes all the changes fromdev. -
Push the local version of
masterto Github:starknet-docs (master) $ git push -f origin master
Github increments the version numbers in
package.jsonandpackage-lock.json, and updatesCHANGELOG.mdwith the descriptions of each PR that was just merged intomaster. -
Update your local
devbranch from the remotemasterbranch:starknet-docs (master) $ git checkout dev starknet-docs (dev) $ git fetch origin starknet-docs (dev) $ git rebase origin/master
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent