Skip to main content

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 the developer-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 documentation
    • dapp contains all the DApp introduction, tutorials, guides
    • mainnet contains all the mainnet documentation
    • community contains all the community documentation
    • examples 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 the articles.mdx file
  • Showcases - for showcases, follow the 2 steps below:
    1. Add the information of showcase at src/data/users.tsx in alphabetical order.
    2. Put a screenshot at src/data/showcase/.

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/currentcp -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.