https://github.com/starknet-io/antora-based-repo-template
Use as a template for a new Antora-based repo that mirrors the starknet-docs repo
https://github.com/starknet-io/antora-based-repo-template
Last synced: 3 months ago
JSON representation
Use as a template for a new Antora-based repo that mirrors the starknet-docs repo
- Host: GitHub
- URL: https://github.com/starknet-io/antora-based-repo-template
- Owner: starknet-io
- Created: 2023-08-10T10:22:12.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-08-10T10:55:47.000Z (almost 2 years ago)
- Last Synced: 2024-12-30T02:28:49.800Z (5 months ago)
- Language: JavaScript
- Size: 70.4 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- Changelog: CHANGELOG.md
- Contributing: contributing_to_docs/doc_guidelines.adoc
Awesome Lists containing this project
README
[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 in 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]
====
== 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: `/public_html/index.html`.
* Run the xref:http_server[http server] packaged with Antora:
+
[source,bash]
----
$ 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
_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 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 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:
+
[source,bash]
----
starknet-docs (master) $ git fetch origin
----
. Merge `dev` into `master` on your local starknet-docs repo:
//. Rebase `dev` into `master` on your local starknet-docs repo:
+
[source,bash]
----
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:
+
[source,bash]
----
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:
+
[source,bash]
----
starknet-docs (master) $ git checkout dev
starknet-docs (dev) $ git fetch origin
starknet-docs (dev) $ git rebase origin/master
----