Static site generator

[codito]

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.

[kamilprusko]

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 👍 For current website we could use https://jinja2docs.readthedocs.io/en/stable/ and a custom script.

As to Markdown:

• for the main page content I'm more in favour of HTML - it can be styled freely, we can control metadata, make images support HiDPI... etc. to me it's a better choice when there is little content.
• for docs I would opt for Markdown

[josehbez]

+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.

[codito]

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

• Use gnomepomodoro.org as the entrypoint, all content is hosted in the Wiki. Homepage simply points there
• Use gnomepomodoro.org as a single place for all content. Stop using wikis
  • Content is created by markdown
  • Content is built into html with github actions by either - a) custom script, or b) framework like mkdocs or gatsbyjs
  • Content hosted in github pages?

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?

[josehbez]

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.

[josehbez]

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

[kamilprusko]

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

• it should be primarily about "About" section and features
• the download - ideally should only have download flatpak option, with more options described in the docs
• needs yo have links to doc pages, otherwise docs are not that discoverable (I placed them above footer)

Here's a draft of docs/website structure:

1. Home (link to homepage)
   1. About
   2. Features + Screenshots
   3. Download Flatpak option
   4. Links to doc pages
2. Download
   1. Download flatpak
   2. Install from system repos
   3. Install from source
3. User Guide
   1. Getting started (after user has installed the app)
      1. Enabling extension
      2. About Pomodoro Technique
   2. Preferences
   3. Integrations
      1. Custom actions
      2. Time tracking services
         1. Toggl
         2. Clockify
         3. Odoo
      3. DBus
4. Get Involved
   1. Development
      1. Getting code
      2. Setting up development envirionment
      3. Building from source (in jhbuild)
      4. Style guide
      5. Writing tests
   2. Documentation
   3. Translating
      1. Adding new translation
      2. Translating
      3. Updating a translation
      4. Testing your translation
      5. Sending your translation
      6. Authors (should be in footer not as a section)
      7. Resources
   4. Maintenance (should we make this public? )
      1. Releasing a version
   5. Report issue

Homepage (unfinished)

Docs

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