This website is made with a PHP wrapper script release/cli-make-website.php on top of Hugo static generator. The theme is derivated from Grav Learn theme to Hugo v2.5.0 for Hugo.
Use only the non extended version of Hugo v0.114.0 to v0.117.0 for your OS. Other versions have not been tested.
You can choose to use a Hugo version installed in the path or in the tools folder directory. If it exists in the tools folder, the latter has priority.
After downloading the binary from github, place it in the tools folder and name it hugo.exe for Windows OS or hugo for other OSes. Give 777 permissions so that the wrapper script can run Hugo.
chmod 777 tools/hugo
To test a copy of the website you must copy release/cnf-release.inc.php.dist file to release/cnf-release.inc.php and modify the WEBSITE_BASE_URL constant in this file to point to a private installation of this site that you have done. For example http://wikindx.test/web.
release/cnf-release.inc.php cannot be commited.
The sources of the website are in the website/web/src folder. The website/web/src/content subfolder contains the markdown files of each page and the website/web/src/static subfolder contains some static files copied at the root of the output website. To learn how to write and organize files, read the online documentation for the Grav learn theme.
To generate the website code, run this command from the cli when your are in the SVN root directory:
php release/cli-make-website.php
The code is generated in two folders :
build/trunk/website/web/trunk: a version for the trunk (will give https://wikindx.sourceforge.io/web/trunk).build/X.Y.Z/website/web/X.Y.Z: a version for the the current release where X.Y.Z is equal to the value of WIKINDX_PUBLIC_VERSION taken from src/core/startup/CONSTANTS.php (will give https://wikindx.sourceforge.io/web/X.Y.Z).For updating the website, generate the code and upload the content of each output folder inside the /home/project-web/wikindx/htdocs/web folder of the SourceForge website FTP. Don’t remove the folders of old versions from the FTP.
Regenerating an older version is not supported. To do this, you have to extract an old revision from SVN because the wrapper script uses the code of the current WIKINDX core and is not able to extract itself the code of the SVN, etc. It’s just an ad hoc script that could change from version to version.
For the online website to be complete you also need to generate and upload the API manual for the same versions. See its own page.
Help Topics are special pages. WIKINDX code points to them. So if you want to rename or update them you have to make sure that the names and the content match with the links and behavior provided in the current application of the trunk code. See the \UTILS\createHelpTopicLink() function in src/core/libs/UTILS.php.
The configuration file is website/web/src/config.toml. It follow the documentation of the theme and Hugo with some exceptions. The pre attribute of the [[menu.shortcuts]] section have been hacked to set the id of a SVN icon bundled in a custom webfont build with the icomoon.io tool. It’s no longer HTML code displayed before an entry of the more menu. The file website/web/src/icomoon.io.wikindx.project.json is a configuration for website/web/src/themes/hugo-theme-learn/static/fonts/custom-font-awesome.svg, and is built with the icomoon.io tool.
Others customization are extensive changes to layout and static files of the theme to optimise the loading time and reduce the size of the generated website. The left column is also entirely customised.
The three files below are called by cli-make-website.php to bundle and minify CSS and JS scripts on the fly during the generation. Only their byproducts are included in the final website. The build script also minifies all HTML files after Hugo generation.
website/web/src/themes/hugo-theme-learn/static/css/minified.css.php
website/web/src/themes/hugo-theme-learn/static/js/minified_header.js.php
website/web/src/themes/hugo-theme-learn/static/js/minified_footer.js.php
All custom fonts have been removed and the data of the search engine are loaded only on the first query.
Chapter titles are displayed in the body.
Mermaid JS is not enabled because this JS file is huge but could be used later.
The last customization is a version selector displayed in the left column of the website. The PHP file website/web/version-switch.php, included in the final website, provides a live list in JSON format of all versions of the website installed on SF. A JS script included in the left column of each page uses this list of versions to allow a visitor to switch the current version instantly, without rebuilding old versions.