Skip to content

Latest commit

 

History

History
156 lines (115 loc) · 6.6 KB

README.adoc

File metadata and controls

156 lines (115 loc) · 6.6 KB
Raw

https://github.com/starknet-io/starknet-docs/issues Static Badge Static Badge

Starknet documentation repository

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

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

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.