Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: Migrate Documentation from GitHub Wiki to Static Website #934

Open
siddharthvipul opened this issue Sep 21, 2023 · 0 comments
Open

Comments

@siddharthvipul
Copy link

GitHub Wiki serves its purpose as a documentation tool but migrating to a static website builder like Jekyll, Hugo, or Sphinx could provide us with greater flexibility, better user experience, and more robust features.
With a static website, we can provide a searchable interface, multi-language support, integrate analytics to understand user engagement, and even version our documentation alongside code releases.
Version control and community engagement are 2 big pieces to care for as a maintainer.

I am proposing we migrate our readme/wiki docs to a static website.

Steps

  • Evaluate static site generators (Jekyll, MKDocs, Hugo, Sphinx, etc.) for compatibility with our needs.
  • Create a prototype site for initial review and feedback. - in a fork
  • Move existing Wiki content to the chosen static site builder. - (merge docs PR)
  • Set up CI/CD pipeline for automated builds and deployments. - (part of PR, GitHub actions to build GitHub pages)
  • Update README and other relevant project files to point to the new documentation site.
  • turn wiki off after a successful migration.

This issue is to hear agreements/disagreement with the proposal and then, decide on the tool. I have my choice, but will leave it for others to chime in :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant