Automate generation/update of SUMMARY.md and TOC

[jgvictores]

Copied from original issue: roboticslab-uc3m/installation-guides#42 From @jgvictores on April 20, 2018 9:11

Automate generation/update of SUMMARY.md. Could be done with Python in few lines of code.

PD: Idea: automate periodically

[jgvictores]

Best if done for trees like https://github.com/asrob-uc3m/tutoriales

[jgvictores]

• https://www.npmjs.com/package/gitbook-summary = https://github.com/imfly/gitbook-summary
• https://github.com/jonschlinkert/markdown-toc

[jgvictores]

Pretty good experiences with both tools above. Drawbacks:

• Summary:
  • Not very good for multilingual repos as we have them (in multilingual repos we use english folder names)
  • Caps: install-pcl -> Install Pcl
• TOC has trouble with UTF8, some symbols must be put manually. However, there could be an option; requires further research and in any case would be upstream.

[PeterBowman]

Some links:

• https://github.com/ekalinin/github-markdown-toc
• http://doctoc.herokuapp.com/
• https://github.com/isaacs/github/issues/215#issuecomment-67204022

[jgvictores]

Yet another resource: https://github.com/rossant/awesome-math/blob/master/build_toc.py

[jgvictores]

"Automate generation/update of SUMMARY.md" https://github.com/roboticslab-uc3m/installation-guides/issues/58 was closed via https://github.com/roboticslab-uc3m/installation-guides/commit/ba39b0bf0f740d54ba7d4d4353cea73a9c8b87f2

[jgvictores]

Note: gitbook-plugin-summary != gitbook-summary (we use this last one)

[jgvictores]

Closing via: TOC: https://github.com/asrob-uc3m/tutoriales/blob/db020e2d663cbb1a2dfb151d60d0c21358a1119a/writing/markdown.md#herramientas SUMMARY: https://github.com/roboticslab-uc3m/installation-guides/blob/8a9968dbf9820df8287c044e1621b61024112c91/install-gitbook.md#additional-tools

[jgvictores]

TOC: https://github.com/asrob-uc3m/tutoriales/blob/db020e2d663cbb1a2dfb151d60d0c21358a1119a/writing/markdown.md#herramientas

Updated with info on https://github.com/aleung/gitbook-plugin-page-toc at https://github.com/asrob-uc3m/tutoriales/commit/087824b195c7a2629c9187c35e4f21848af1f9d6

[jgvictores]

Updated with info on https://github.com/aleung/gitbook-plugin-page-toc at asrob-uc3m/tutoriales@087824b

https://github.com/roboticslab-uc3m: gitbook-plugin-page-toc now used on the 3 repos that use gitbook as of https://github.com/roboticslab-uc3m/developer-manual/blob/357d3d8644ca55e7a6961f702ac95cf3be8e57d4/appendix/repository-index.md (aproximate commits):

• https://github.com/roboticslab-uc3m/developer-manual
  • https://github.com/roboticslab-uc3m/developer-manual/commit/8f72baec935707b0005ff847f96719ec6eb143e7#diff-90a7578caf8760be75c2b36f8b110073e494adf0a3264e624874098ed93acbab
• https://github.com/roboticslab-uc3m/teo-developer-manual
  • https://github.com/roboticslab-uc3m/teo-developer-manual/commit/973777b5905d71dab9a3b2e76a8b8deb97208569#diff-b2c0e7e29a97e5b2c283c61f93944049e35d647929963974601dd0bd3d6a4daa
  • https://github.com/roboticslab-uc3m/teo-developer-manual/commit/dd9c1e4f3a5f4ae491f36b3d6621fb2de8aa8995#diff-90a7578caf8760be75c2b36f8b110073e494adf0a3264e624874098ed93acbab
• (atow, this repo is slightly different as it is the only one with an auto-generated SUMMARY): https://github.com/roboticslab-uc3m/installation-guides
  • https://github.com/roboticslab-uc3m/installation-guides/commit/746694340a372e53a651ecccc1d6105e0e01635f
  • https://github.com/roboticslab-uc3m/installation-guides/commit/54b6610cbaa21fb2f956c55a8134eab25b07fd4b#diff-7acc9a0442f2b78d2a74fb79767c53942d9fb9593595d0a498962026bd3af393

https://github.com/asrob-uc3m: gitbook-plugin-page-toc now used on the 2/6 repos that use gitbook (open-source, legacy, migrated to robots server) as of 2020/11/13 state of https://github.com/asrob-uc3m/actas/issues/148#issuecomment-699609887

• https://github.com/asrob-uc3m/tutoriales
  • https://github.com/asrob-uc3m/tutoriales/commit/c01df2730f29d4e79914d9a3b4f6e255d37f03c1
  • https://github.com/asrob-uc3m/tutoriales/commit/ba7ed598e5353d2ff94002f93e5070c27f48759d
• https://github.com/asrob-uc3m/rd-ambassador
  • https://github.com/asrob-uc3m/rd-ambassador/commit/3165d644711fdaae23dd042347445a9833ad5ed1

As a result, many commits have also been dedicated to:

• Removing manually added TOC from pages
• Improving header levels that were mixed up in many cases, as well as more fixes via Code's md linter ^^

[jgvictores]

Note that the plugin mechanism seems much more elegant. Has been adopted fot TOC. A solution such as https://github.com/julianxhokaxhiu/gitbook-plugin-summary (if satisfies requirements) could be adopted org-wise, as an alternative to the current approach of https://github.com/roboticslab-uc3m/installation-guides/tree/09ffe48fd158656bb6359b4f3969948d2a94d4cd