SoK/2021/StatusReport/Suraj Kumar Mahto

Porting docs-kde-org to Hugo

Abstract

docs-kde-org is the central website which hosts the KDE user documentation (development & stable release) in over 25 languages. In this task, I am revamping the old docs website currently hosted at domain docs.kde.org . It uses a python script to fetch the newest version of the documentation from Git (for English) and Subversion (for other languages) and build HTML and PDF files from the DocBook sources. The custom python script is refactored first.

Static site generators like Hugo would be great to shift the current website as it reduces the server dependencies since the website builds only on its updation. Also the use of markdown for content makes the website updation easy even for Contributors who don’t have any prior website maintenance experience. For the site structure similar to now, we are using Docsy Hugo.

Links

• Repository:-Documentation Website dev repo
• Proposal:-Accepted proposal
• Blog - Phase 1:- Blog

Mentors

• Carl Schwan
• Anuj Bansal

Phase 1

• Refactored the python scripts(docgenerator.py) to create markdown files of each category containing json data of all the apps in that category. For example, documentation.md will have

{

 "name": "documentation",
 "apps": [
   {
     "name": "digikam-doc",
     "doc": [
       {
         "latest": "/trunk5/en/digikam-doc/digikam",
         "stable": "/stable5/en/digikam-doc/digikam"
       },
       {
         "latest": "/trunk5/en/digikam-doc/showfoto",
         "stable": "/stable5/en/digikam-doc/showfoto"
       }
     ]
   }
 ]

}

• The above thing creates the basic site structure for hugo.
• Used and modified layouts from develop-kde-org for docsy hugo layout.

Phase 2

• Used the layouts/hig/ (from develop-kde-org docsy) as the default layouts.
• Modified the layouts to populate the docbook's paths link.
• Implement site wide Search.

Phase 3

• Implemented separate pages for each language.
• Modified the docgen script to generate separate data for different languages. Now each category file having the json metadata of the respective category is inside content-trans/<lang> respectively for each language.

(MR Link to be merged)