The Starknet docs website, https://docs.starknet.io, is built using Antora, a static website generator for AsciiDoc.
You don’t need to install Antora to preview the website. This repo includes an embedded Antora installation, which is referred to in the Antora documentation as a local installation.
You must have an active Node.js LTS release on your machine. See the Antora documentation for your OS:
Tip
|
Install the optional http server Antora provides so you can view the output in a local web server |
-
Clone this repo to your local machine. Using a fork is optional.
-
When naming a branch, if you do not use a fork, use the following format:
<name>/<short_description>
-
When creating a new PR, tag one or more of the following as reviewers:
stoobie
,JameStark
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.sh
build 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
master
branch. -
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
dev
intomaster
on your local starknet-docs repo:starknet-docs (master) $ git merge dev
Your local version of
master
now includes all the changes fromdev
. -
Push the local version of
master
to Github:starknet-docs (master) $ git push -f origin master
Github increments the version numbers in
package.json
andpackage-lock.json
, and updatesCHANGELOG.md
with the descriptions of each PR that was just merged intomaster
. -
Update your local
dev
branch from the remotemaster
branch:starknet-docs (master) $ git checkout dev starknet-docs (dev) $ git fetch origin starknet-docs (dev) $ git rebase origin/master