Skip to main content

Document Contribution

tip

Warudo Handbook is now open-source on Github, check it out!
https://github.com/HakuyaLabs/warudo-docs/

While using Warudo's flexible features, clear and understandable documentation are essential to let everybody easy to use Warudo.

The Warudo handbook proudly uses Docusaurus as site framework, and the content is written in Markdown. We have added some great features which provided in-app help function in Warudo app.

The Warudo handbook is open-source project. If you find anything hard to understand or want to provide new content, such as tutorials or guidance, feel free to create issues on GitHub, or directly contribute by submitting code or translations to the GitHub project. Your name will appear in the contributors list at the bottom of the documentation!

How to Contribute​

Provide Feedback and Suggestions via GitHub Issues​

Providing feedback directly through GitHub Issues is a straightforward and simple way. We have set up some issue templates to help submit issues.
https://github.com/HakuyaLabs/warudo-docs/issues

tips: The feedback here is for the Warudo handbook site. For discussions about the Warudo software itself, feel free to join Discord channels.
https://discord.gg/warudo

Submit Code and Become a Contributor​

If you are familiar with Git and dev staff, you can directly submit a Merge Request on GitHub to contribute code.

If you are not familiar, don't worry. The following content will guide you on how to run a local version of the Warudo Handbook and make your own modifications.

Technical Details​

Directory Structure​

PathContent
/docsEnglish docs (main)
/i18n/zh/docusaurus-plugin-content-docs/currentChinese docs (translate)
/i18n/jp/docusaurus-plugin-content-docs/currentJapanese docs (translate)

Non-English version files should be exactly the same structure as the English version so that the language switch can work accurately.

tip

The navigation bar on the left side is also generated by English version files, It's recommended to copy every file in /docs folder to /i18n/[lang]/docusaurus-plugin-content-docs/current and make sure that every file aligns in a different language.

Commands​

CommandDescription
yarnInstall dependencies
yarn start:enStart English version
yarn start:zhStart Chinese version
yarn start:jpStart Japanese version
yarn start:allStart multi-version at different port
yarn buildBuild site

Running local development site​

If you are not familiar with dev staff, don't worry, let's get start.

Document development tutorial

Prepare environment​

First, download the runtime.

  • Node.js download: https://nodejs.org/en/download/
    Node.js is the programming language we used.
    Select LTS version - installer (.msi/.exe for Windows, .pkg for macOS).

  • GitHub Desktop download: https://desktop.github.com/
    GitHub Desktop is a great version control software for us to manage and commit changes.

  • VSCode download: https://code.visualstudio.com/
    VSCode is a common editor that works great for front-end sites like this one, you can also use other text editors.

Using command line​

  • For Windows, use Win+R and enter cmd to open the terminal.

  • For macOS, use the Terminal app in your lunchpad.

After installation, you should able to use the node -v command to see node.js version on the terminal.

Set up the project using GitHub desktop​

  • Login Github account

  • Search for HakuyaLabs/warudo-docs

  • Clone project
    Then the project has been downloaded to your computer.

  • Click Current branch - New branch - input name - Create branch
    So that you can edit files in your independent branch.

  • Click Publish branch
    Event one should see your branch and you are ready to start edit.

Run local site​

Open the terminal.

  • cd <path_for_your_dev_folder>
    Jump into the folder where we place site files.

  • corepack enable
    That set up package manager we used for node.js.
    Usually you just need run this command once.

  • yarn
    Install dependencies.
    When project dependencies (package.json) updated, re-run this command is necessary.

  • yarn start:en Start EN version
    yarn start:zh Start ZH version
    yarn start:all Start multi-version at different port

Then you are all set, you can view local site on your machine!
When you change and save the docs, the browser will automatic refresh.
Try it out, and go ahead start editing document files!

Start editing​

  • Edit markdown files and check live page in browser

Most document files are saved as .md or .mdx, known as Markdown files,
which is just plain text with some formate code in it.

Commit & Upload your changes​

After saving all the files that you changed.

  • Open the Github desktop, then you can see all the changes on the left side.
    Check all the changed files you want to commit.
    Enter a summary, and click Commit.

  • You have committed your changes and you should see it in the History panel.

  • But it is just on your computer right now.
    To publish to Github, click Push Origin.

  • Yay! Everyone should see it on github.

Contact Warudo Handbook Maintenance Members for Review and Publication​

  • Submit a pull request and contact the documentation maintenance members in the community to merge your changes and publish them!

Add Your Own Name​

At the bottom of each document, there is a section of code that marks the editors of the document. When you modify or complete a document, don't forget to add your name here. The avatar will be automatically fetched through your GitHub ID.

<AuthorBar authors={{
  creators: [
    {name: 'Your Name', github: 'Your GitHub ID'},
  ],
  translators: [
    {name: 'Your Name', github: 'Your GitHub ID'},
  ],
}} />

Contributions

Edit on Github

Authors

Nekotora
Last updated on 2024.06.26