Read Me

Table of Contents

Previewing the website on your local machine
Git-related info
Tips on authoring
Building and previewing content locally
Releasing Starknet docs on Github

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

Previewing the website on your local machine

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.

Prerequisites

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

Tips on authoring

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

Building and previewing content locally

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

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

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 into master on your local starknet-docs repo:
```
starknet-docs (master) $ git merge dev
```
Your local version of master now includes all the changes from dev.
Push the local version of master to Github:
```
starknet-docs (master) $ git push -f 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.

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

dmitrytarassov/starknet-docs