Contributing
Mixin and this documentation are open source. We are now welcoming contributors to collaborate on these.
Preparation
Mixin developer documentation is based on Docusaurus, a static site generator for React.js.
- You need to ensure that you have Yarn installed
- Clone the repository of the document
- Run
yarn
in the root of thedeveloper-docs
- Run
yarn start
to preview the documentation
Document Structure
The documentation is organized in the following way:
- all source is in the
docs
directory - the
docs
directory contains the following subdirectories:api
contains all the API documentationdapp
contains all the DApp introduction, tutorials, guidesmainnet
contains all the mainnet documentationcommunity
contains all the community documentationexamples
contains all the examples
The sidebar.docs.js
file contains the sidebar of the documentation, which is separated into 2 sections: 'Docs' and 'API'.
Contributing new content
Writing new documentation
All content is written in Markdown format with react components extension.
The first step to contribute is to create a new markdown file at the right place in the docs
directory.
For example, this document is in docs/commnuity/contributing.mdx
.
If you are writing new content for specific topics, you can put them in the existed files:
Articles
- for articles, please update thearticles.mdx
fileShowcases
- for showcases, follow the 2 steps below:- Add the information of showcase at
src/data/users.tsx
in alphabetical order. - Put a screenshot at
src/data/showcase/
.
- Add the information of showcase at
Using components
There are some built-in components that can be used in the documentation in the directory src/components/api
<APIEndpoint>
is a component that renders an API endpoint<APIMetaPanel>
is a component that renders an API's information including the authorizations and limitation<APIParams>
is a component that renders an API's parameters<APIPayload>
is a component that renders an API's payload<APIRequest>
is a component that renders an API's request
Please refer to the any document of 'API' section for the usage of them.
Using partials
There are code snipples that can be used in the documentation in the directory docs/partials
. Please consider using them.
Adding to the sidebar
After you have created a new markdown file, you need to add it to the sidebar.
The sidebar file is sidebar.docs.js
and it is located in the docs
directory.
Making a copy of the new file for translation
If you are adding a new documentation, you need to put a translation file at i18n/$LANG_CODE
directory.
For example, this document is docs/community/contributing.mdx
and its zh-CN
translation is i18n/zh-CN/docusaurus-plugin-content-docs/current/zh-CN/docs/community/contributing.mdx
.
Translation
Generate new translation files for new languages
If you're the maintainer of this project, please follow the instructions in the i18n tutorial to add a new language.
Translate the index page
Please follow the instructions here to translate your index page and react components.
Generate/Update json files
yarn run write-translations --locale $LANG_CODE
The $LANG_CODE
is the language code of the language you want to generate. For example, if you want to generate the translation files for the French language, you should use fr
.
The translation files are generated in the i18n/$LANG_CODE/
directory.
Generate Markdown files
Copy the docs Markdown files to i18n/$LANG_CODE/docusaurus-plugin-content-docs/current
, and translate them:
mkdir -p i18n/$LANG_CODE/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/$LANG_CODE/docusaurus-plugin-content-docs/current
Translate the documents
All the documents are placed in the i18n/$LANG_CODE/
according to the languages.
i18n/$LANG_CODE/code.json
: the translation of the index page and the text used by docusaurus.i18n/$LANG_CODE/docusaurus-theme-classic/footer.json
: the translation of footer.i18n/$LANG_CODE/docusaurus-theme-classic/navbar.json
: the translation of navbar.i18n/$LANG_CODE/docusaurus-plugin-content-docs/current.json
: the label of category on sidebar.i18n/$LANG_CODE/docusaurus-plugin-content-docs/current/**
: the markdown files of documents.
Preview the translation
yarn run start --locale $LANG_CODE
Join our developer group
To participate in Mixin development, search 7000104112
in Mixin Messenger and join the developer group.