Open codito opened 3 years ago
Do you have in mind new docs? Or replacing the whole page.
Some static site generation indeed would be helpful to split content from the template :+1: For current website we could use https://jinja2docs.readthedocs.io/en/stable/ and a custom script.
As to Markdown:
+1 I'm more in favour of HTM -- use as home page.
For wiki Markdown, We would easily do the documentation for any feature, guideline for enduser or guideline for devs.
Because I will like join https://github.com/gnome-pomodoro/gnome-pomodoro/wiki and https://github.com/gnome-pomodoro/gnome-pomodoro-tracking/blob/master/assets/clockify/README.md , and have in one site. With an endpoint gnomepomodoro.org/wiki|docs.
Do you have in mind new docs? Or replacing the whole page.
I had new docs in mind - installation/usage/integrations for end users, troubleshooting/contribution guide for advanced users/developers. It will be great if the content could be added by the community with ease and without deep knowledge of html/css.
Wikis are a great fit, but discoverability may be a problem if the content is large or hierarchical.
Love the idea of having a single endpoint for all docs and separating the content from style. Would suggest gatsbyjs as an option too as it provides much more control over the styling etc. with the docs sourced as markdown and pages (e.g. homepage) built as a react component. All of these are converted into html after build.
Summarizing the options below based on discussion
mkdocs
or gatsbyjs
I'd prefer (2) as it will give us a single place to find everything about the app. Did I miss any options? What do you think?
Content hosted in github pages?
if after to build is static site, yes.
Content is built into html with github actions by either - a) custom script, or b) framework like mkdocs or gatsbyjs
a) We need design the new doc section to be friendly. Doc routing b) We need migrate current home-page or only use for new docs.
+1 option b -- first create new docs and after migrate honne-page, this my opinion.
I suggest this:
1) Keep this website 2) Inside this repo add
docs/
users/
devs/
integrations/
gnome-pomodoro-tracking/
Track-your-time-with-toggl.md
task-warrior-time-warrior/
assets/img1.png
TITLE-GUIDE.md
3) Use gitbook.com or simillar with available API
4) Create a script that reads docs
and synchronize using GH Actions.
5) Create a subdomain docs.gnomepomodoro.org
What do you think? @gnome-pomodoro/devs
I've been playing with mkdocs in wip/mkdocs branch. I like that it's purpose build and it's quite nice out of the box without plugins. A custom homepage can be made using theme overrides. I haven't looked much at gatsbyjs, it seems intimidating by comparison :D
As to gitbook.com. I'd rather have source files available here on github for everyone to edit, with no additional accounts.
The more I play with it, the more I think that the homepage needs to be reorganised
Here's a draft of docs/website structure:
If you'd like to play with it. Quick usage:
$ ./env.sh
$ mkdocs serve
Then go to http://127.0.0.1:8000/ . Restart mkdocs serve
when making changes to mkdocs.yml
.
What do you think? @gnome-pomodoro/devs
Is it worth considering a static site generator for the website? E.g. https://www.mkdocs.org/
It will make managing content easier with markdown or similar.