Contribute docs
This document is currently in public preview and may change significantly as feedback is captured from readers like you. Click the Request an update button at the top of this document or join the Arbitrum Discord to share your feedback.
The docs.arbitrum.io
docs portal is the single source of truth for documentation that supports Offchain Labs' product portfolio. Contributions are welcome from the entire Ethereum community.
This document shows you how to craft and publish Arbitrum documentation. Familiarity with Markdown syntax, Github, and Docusaurus is expected.
Add a new core document
If a document isn't in a Third-party content
sidebar node, it's a core document. To contribute a new core doc:
- Begin by creating a branch (internal) or fork (external) of the Arbitrum docs repo.
- Issue a
Draft
pull request intomaster
. Pull requests intomaster
generate a preview of your changes via a PR-specific Docusaurus deployment; this preview will update as you push commits to your remote. - Include answers to the following questions in your PR description:
1. Audience: Who am I writing for?
2. Problem: What specific problem are they trying to solve?
3. Discovery: How are they looking for a solution to this problem? What search terms are they using?
4. Document type: Which document type is most suitable?
5. Policy acknowledgment (Third-party docs only): Do you agree to the third-party content policy outlined within "Contribute docs"? - As you craft your contribution, refer to the document types, Style guidance, and other conventions below.
- Mark your PR as
Open
when it's ready for review.
Add a new third-party document
Third-party docs are documents that help readers of Arbitrum docs use other products, services, and protocols (like the ones listed in the Arbitrum portal) with Arbitrum products.
See Contribute third-party docs for detailed instructions.
Request an update
If you'd like to request an update or share a suggestion related to an existing document without submitting a pull request to implement the improvement yourself, click the Request an update
button located at the top of each published document. This button will lead you to a prefilled Github issue that you can use to elaborate on your request or suggestion.
Add a new translation page
If you would like to participate in translating the Arbitrum docs, you can:
- Check whether
/website/i18n
has a corresponding language (currently there areja
andzh
). If not, you can use the following command to add it (we take adding French as an example):
cd ./website
npm run write-translations -- --locale fr
It will help generate folder website/i18n/fr
.
- Create the folders
current
andtranslated
under the newly generated folderwebsite/i18n/fr/docusaurus-plugin-content-docs
:
mkdir i18n/{Your_language}/docusaurus-plugin-content-docs/current && mkdir i18n/{Your_language}/docusaurus-plugin-content-docs/translated
-
Translate one of more docs files located in
/arbitrum-docs
. -
Place the translated document into the folder
i18n/{Your_language}/docusaurus-plugin-content-docs/translated
according to its relative path inarbitrum-docs
. For example, if you translated/arbitrum-docs/how-arbitrum-works/arbos/introduction.md
, then its path in i18n should bei18n/{Your_language}/docusaurus-plugin-content-docs/translated/how-arbitrum-works/arbos/introduction.md
.
Test run:
- Check that the i18n settings in
website/docusaurus.config.js
have included your new language:
i18n: {
defaultLocale: 'en',
// locales: ['en', 'ja', 'zh'],
locales: ['en'], // You can add your new language to this array
},
- Check whether the
locale Dropdown
component exists in navbar, if not, add it:
navbar: {
title: 'Arbitrum Docs',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
href: '/welcome/arbitrum-gentle-introduction',
},
items: [
// note: we can uncomment this when we want to display the locale dropdown in the top navbar
// if we enable this now, the dropdown will appear above every document; if `ja` is selected for a document that isn't yet translated, it will 404
// there may be a way to show the dropdown only on pages that have been translated, but that's out of scope for the initial version
{
type: 'localeDropdown',
position: 'right',
}
],
},
- Build translation and docs:
yarn build_translation && yarn build
- Start docs:
npm run serve