New Documentation Site Engine

Mentee: Rajiv Ranjan Singh
Mentors: Indermohan Singh, Meg McRoberts, Suraj Banakar

Rajiv Ranjan Singh
Final Year UG student @ JSSATE Bengaluru
India

What has gone well?

  • Initialization and deployment of the documentation engine based on Docusaurus from scratch and adding new UI and UX changes.
  • Search functionality.
  • Versioning support.
  • Multiple repository docs support.
  • Implemented all SEO approaches listed in https://docusaurus.io/docs/seo like adding metadata in site configuration, adding metadata for all single pages, adding metadata in the front matter of all markdown files, etc.
  • Dark mode support.

What problems did you have and how did you solve them?

  • Moving content from an older doc site to a new doc engine is challenging because of the large number of contents. To solve this issue I am following the lists given by Meg here.
  • Older doc site content has Hugo-based code snippets and templates that can not be run in Docusaurus so we have to convert to Docusaurus-based code i.e. JS or JSX. I am solving this manually.

What additional work do you expect to complete in Phase I?

  • Moving all the content from the older doc to the new doc engine.
  • Writing a robust GitHub Action or equivalent solution to pull the docs from other repo to a new doc engine and should also organize the content in proper structure.
run: |
    git clone https://.:${{ secrets.GITHUB_TOKEN }}@github.com/project target
    rm everything but the .git directory
    copy source\files target
    cd target
    git add .
    git diff-index --quiet HEAD || git commit -m "Automatic publish from github.com/project"
    git push target master

Mobile View

  • The New Documentation Engine is responsive and works fine in mobile view.

  • We can split the code snippets into multiple lines or we can keep it one line.

Phase 2 Work

  • Writing a GitHub Action to move the content from an older doc site to a new doc engine and structure the docs properly in specified folders.
  • Adding Vale linter or equivalent linter for doc quality checks.
  • Adding Prettier GitHub Action support to format markdown docs.
  • Integrating Lighthouse in the docs engine to check the quality of the documentation. We will be able to audit the performance, accessibility, SEO, etc of the doc site.
  • Adding other GitHub Action to check broken links, spelling mistakes, check code style, etc.

Thank You 🎉,

https://github.com/iamrajiv/GSoC-2022

Twitter: @therajiv
Portfolio: https://iamrajiv.github.io