Website

This website is a port from Gitbook of the Armada Alliance Docs to Docusaurus 2, a modern static website generator.

The website is deployed at Github Pages https://armada-alliance.com/docs/

Local Development

Clone the repository locally enter the new project folder.

git clone https://github.com/armada-alliance/docs.git
cd docs/
npm install
npm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Creating a Doc

All the docs are inside the docs folder .

To add a new one just create an md or mdx (if using JSX components) file there.

Please refer to the Docusaurus Markdown Features Guide to know about the syntax and components that you can use.

• Markdown Features
• MDX and React
• Tabs
• Code Blocks
• Admonitions | Alerts
• Headings and Table of contents
• Assets and Images
• Markdown Links
• Head Metadata

To emmbed videos, use the iframe html tag with 100% width and 600px height:

<iframe
  width="100%"
  height="600"
  src="https://www.youtube.com/embed/oP3jZyPxB-I"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
></iframe>

Sidebar Links

The sidebar is not automatically generated, in order to add new links or documents to it you have to modify the sidebar.js file .

Check the Docusaurus Docs to learn about this component.

Translations using Crowdin

Crowdin is a translation SaaS, offering a free plan for open-source projects.

We recommend the following translation workflow:

• Upload sources to Crowdin (untranslated files)

npm run crowdin:upload

• Use Crowdin to translate the content
• Download translations from Crowdin (localized translation files)

npm run crowdin:download

Crowdin provides a CLI that is installed as dependency to this project, this CLI allows to upload sources and download translations, The crowdin-v2.yaml configuration file is convenient for Docusaurus, and permits to download the localized translation files at the expected location (in i18n/[locale]/..).

Read the official documentation to know more about advanced features and different translation workflows.

This repository uploads the source files and downloads the translations automatically on every deploy to GH-Pages.

For convenience you can use the following command to upload and download:

npm run crowdin:sync

Adding a new language

After adding a language in Crowdin UI, you can enable it to make it available on the website adding it to the locales array .

Add the locale to crowdin-v2.yaml exported_languages array too, although it doesn't seem to be taking it into consideration at this moment.

For a deep understanding of the translation workflow please refer to the Docusarus Documentation

Before you can use Crowdin is mandatory to set the environmental variables.

Environmental Variables

Create a .env file containing this two variables:

CROWDIN_PERSONAL_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
CROWDIN_PROJECT_ID=XXXXXX

Replace CROWDIN_PERSONAL_TOKEN value with your own personal token

Do the same with CROWDIN_PROJECT_ID, you can find your project's id at https://crowdin.com/project/<MY_PROJECT_NAME>/settings#api

Build

npm run build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

GIT_USER=<Your GitHub username> USE_SSH=true npm run deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

Don't forget to create the environmental variables for Crowdin as Github secrets or the build will fail.

For automated CI a Github workflow called translate_and_deploy.yml is avaliable inside .github/workflows folder.