From bffd1a2c21f7a5ea21683550f58820ba8885f870 Mon Sep 17 00:00:00 2001 From: Patrick Bos Date: Tue, 17 Oct 2023 12:35:02 +0200 Subject: [PATCH 1/2] Add technical details to Contributing page Implementation and configuration details are necessary context for some high-level contributions. For instance, #266 about a "successful build" GH Action is not applicable in light of these details. Fixes #266. --- CONTRIBUTING.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 331c1135..ab0439a4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,3 +46,21 @@ To see who is responsible for which part of the guide see [chapter_owners.md](ch We host a PDF version of the guide on [Zenodo](https://doi.org/10.5281/zenodo.4020565). To update it a [new release](https://github.com/NLeSC/guide/releases) needs to be made of the guide. This will trigger a GitHub action to create a new Zenodo version with the PDF file. + +# Technical details + +The basics of how the Guide is implemented. + +The Guide is built on [docsify](https://docsify.js.org) and hosted on GitHub Pages. +Deployment is "automatic" from the main branch, because docsify requires no build step into static HTML pages, but rather generates HTML dynamically from the MarkDown files in the Guide repository. +The only configuration that was necessary for this automatic deployment is: +1. The [index.html](https://github.com/NLeSC/guide/blob/main/index.html) file in the root directory that loads docsify. +2. The empty [.nojekyll](https://github.com/NLeSC/guide/blob/main/.nojekyll) file, which tells GitHub that we're not dealing with Jekyll here (the GitHub Pages default). +3. Telling GitHub in the Settings -> Pages menu to load the Pages content from the root directory. + +Plugins that we use: +- The [docsify full text search plugin](https://docsify.js.org/#/plugins?id=full-text-search) +- The [docsify Google Analytics plugin](https://docsify.js.org/#/plugins?id=google-analytics) +- [Prism](https://docsify.js.org/#/language-highlight) is used for language highlighting. + +If you want to change anything in this part, please discuss in an issue. From 0cd401128618e0cab6806f6e5ba09ea4e3183897 Mon Sep 17 00:00:00 2001 From: Patrick Bos Date: Tue, 24 Oct 2023 10:44:48 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Stefan Verhoeven --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab0439a4..1b455db0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,12 +51,13 @@ To update it a [new release](https://github.com/NLeSC/guide/releases) needs to b The basics of how the Guide is implemented. -The Guide is built on [docsify](https://docsify.js.org) and hosted on GitHub Pages. +The Guide is rendered by [docsify](https://docsify.js.org) and hosted on GitHub Pages. Deployment is "automatic" from the main branch, because docsify requires no build step into static HTML pages, but rather generates HTML dynamically from the MarkDown files in the Guide repository. The only configuration that was necessary for this automatic deployment is: 1. The [index.html](https://github.com/NLeSC/guide/blob/main/index.html) file in the root directory that loads docsify. 2. The empty [.nojekyll](https://github.com/NLeSC/guide/blob/main/.nojekyll) file, which tells GitHub that we're not dealing with Jekyll here (the GitHub Pages default). 3. Telling GitHub in the Settings -> Pages menu to load the Pages content from the root directory. +4. The [_sidebar.md](https://github.com/NLeSC/guide/blob/main/_sidebar.md) file for the table of contents. Plugins that we use: - The [docsify full text search plugin](https://docsify.js.org/#/plugins?id=full-text-search)