starknet-docs
starknet-docs copied to clipboard
The repo for Starknet's developer documentation. Includes contribution guidelines and the Starknet documentation supplementary style guide
[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
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
[email protected]:starknet-io/starknet-docs.git
: