[id="readme"] ++++

++++

= Starknet documentation repository :toc: :toclevels: 1

The Starknet docs website, https://docs.starknet.io, is written in https://asciidoc.org/[AsciiDoc] and is built using link:https://antora.org/[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 xref:#different_ways_to_contribute[Different ways to contribute].

|Are there any basic guidelines to help me? | For basic guidelines to help us keep our content consistent, see link:/contributing_to_docs/doc_guidelines.adoc[Documentation guidelines].

| Is there a style guide and writing guide I should use? | See the xref:contributing_to_docs/starknet_docs_style_guide.adoc[Starknet documentation supplementary style guide].

|How do I set up my workstation? |See xref:contributing_to_docs/setting_up_environment.adoc[Setting up your environment].

|===

[#different_ways_to_contribute] == Different ways to contribute

There are a few different ways you can contribute to Starknet documentation:

• Create a link:https://github.com/starknet-io/starknet-docs/issues[GitHub issue].
• Submit a pull request (PR). You can create a local clone of your own fork of the link:https://github.com/starknet-io/starknet-docs[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 https://github.com/orgs/starknet-io/teams/starknet-docs[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

• xref:contributing_to_docs/starknet_docs_style_guide.adoc[Starknet documentation supplementary style guide]: General style guidance and writing guidance.

For information on writing in AsciiDoc, see:

• link:https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]
• link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[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 link:https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference for Red Hat Documentation]

== Before you begin

. Install yarn if it's not already installed. . Install npx if it's not already installed. . Clone this repo, either from a fork, or if you are an official collaborator, then directly from starknet-io/starknet-docs. . Change to the starknet-docs directory. . 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:

. Build the content by running the build_local_site.sh build script: + [source,bash]

./build_local_site.sh

+ 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 xref:http_server[http server] packaged with Antora:

• [source,bash]

  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:

• [source,bash,subs="+quotes,+macros"]

  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 link:https://docs.starknet.io[docs.starknet.io].

GitHub actions create Git tags and releases that appear at the repo’s link:https://github.com/starknet-community-libs/starknet-docs/releases[Releases] and link:https://github.com/starknet-community-libs/starknet-docs/tags[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:

• [source,bash]

  starknet-docs (main) git pull

• Do a rebase from git@github.com:starknet-io/starknet-docs.git:

• [source,bash]

  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 git@github.com:starknet-io/starknet-docs.git. So when rebasing, use upstream instead of origin in the above commands.