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

Centralize User Documentation #11

Open
romangg opened this issue Oct 5, 2024 · 1 comment
Open

Centralize User Documentation #11

romangg opened this issue Oct 5, 2024 · 1 comment
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@romangg
Copy link
Member

romangg commented Oct 5, 2024

At the moment we have a lot of documentation in the Manjaro Wiki and we had some on the old website.

We should try to centralize this in a single place. And having it in a more "book-style" format like other projects (example) instead of a wiki format would probably be also a good change.

Requirements:

  • content in Git repo, allows MRs by community
  • optionally a CMS for the team to quickly edit content but not necessary since GitHub has an online editor
  • modern design similar to our website including dark mode
  • tech: vue.js would be good but not necessary. astro also an option
  • must have i18n support

Tech

Candidates are Astro, VitePress or Nuxt what we use already on our website.

@romangg romangg added documentation Improvements or additions to documentation enhancement New feature or request labels Oct 5, 2024
@cfinnberg
Copy link
Collaborator

cfinnberg commented Oct 6, 2024

Started a test site with VitePress at https://cfinnberg.github.io/mdocs/. Proof of concept will be developed on that site.

Edit:
Let's add some additional info here (I don't want to add a comment every time I add a small piece of info)

More requirements:

  • Search

Some notes:

  • Although VitePress has some i18n support, it seems that the best option is to use some module like lunaria. VitePress itself uses it, but it's in public beta state yet (breaking changes are possible)
  • With default VitePress the language switcher in the nav menu always shows all the languages, even if the page in question is not translated or only translated to some of them. The rest of languages, when selected, show a 404 page.
  • Dark mode is supported by the default theme. Not sure if the default theme will be used at the end.
  • Default theme seems to have a nice and modern look. But let's see if it fits our purpose.
  • Base site was easy to set up and deploy to Github pages. Posibility of Dockerization should be considered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants