New documentation can not be found by Google

[dpolivaev]

Docsify uses on-the-fly html generation by java script.
Unfortunately it has a consequence that no documentation pages appear in results of Google search.
It makes the site almost useless.

See
docsifyjs/docsify#761

The next major docsify should support static html generation to solve this problem, but development makes not progress since the beginning of 2021, and the mentioned issue was discussed in 2019.
docsifyjs/docsify#657

Do you have any ideas what we could do?

[macmarrum]

I'm not sure how a search engine (Google) determines the content of a page for its index.

My initial idea is to generate a tree of static pages based on the dynamic ones.
Each page would have no (visible) content except for a link to its dynamic counterpart.

[dpolivaev]

I have no idea. I thought we might have to reconsider using docsify.

[dpolivaev]

If we use both static and dynamic pages, then the static pages are likely to get extremely low ranking because nobody would link to them

[dpolivaev]

Therefore we might to need a static site generator replacing docsify

[macmarrum]

Looks like it

[euu2021]

The issue had activity 23 days ago. But, it doesn't seem to be close to a release.

---

Github wikis have the same problem, and they suggest using Github pages:

[dpolivaev]

I think we can use mdBook generator
in combination with GitHub Pages, GitHub CI/CD, and GitHub Actions .

For local development, mdBook can be installed.

The GitHub Actions allow to generate HTML pages and to push them to a branch taken by GitHub pages for distribution.

@macmarrum How do you see it? Would you like to spend time making it happen either on your own or together with me?

[dpolivaev]

MdBook supports a collapsible table of contexts, searchable pages, and switchable light and dark themes.
It is compiled for Windows, Linux, and MacOS so that everyone can easily use it for local development.
Jekyll can not run on Windows as easy, see https://jekyllrb.com/docs/installation/windows/

I find MdBook documentation to be nicely structured and easy to understand.

Is there a reason to use Jekyll? Which one?

[macmarrum]

I know little about any of the applications. I am fine to try mdBook.

There is some progress: mdbook ran in GitHub Actions, though no end result is visible in GitHub Pages.

• https://github.com/macmarrum/freeplane-docs/runs/8179533170?check_suite_focus=true

I still need to understand the process.

[dpolivaev]

Could you add me as a collaborator to your repository so that I can have a look?

[dpolivaev]

Anyway great progress

[dpolivaev]

I would probably generate html in a separate directory (maybe html-root) to separate it from the rest and configure GitHib pages to use it.

[dpolivaev]

@macmarrum I would like to finalize the move from docsify to mdbook myself based on our learnings.
It requires changing the directory structure and introducing the src/doc directory and moving everything there.
I have got some time for this work.

Would you please allow me to do this change? I need your ok because uncoordinated change of the directory structure can cause merge conflicts.

[macmarrum]

@dpolivaev Please feel free to go on.

[dpolivaev]

I have merged the new version. It is not perfect and you'll undoubtedly find out how to improve it.
But it was a significant amount of work and I have finished it.

[macmarrum]

Well done 🚀

[dpolivaev]

Gitpod IDE works with mdbook now, I have also fixed the README

[macmarrum]

@dpolivaev I have reviewed GitHub Actions for mdbook and proposed some changes in

• add new-generation workflow #88

Could you please have a look at my comments to the PR?