From 8e67a740fc8346acd2b0e0d6b483698e5300281d Mon Sep 17 00:00:00 2001 From: pacien Date: Thu, 1 Dec 2022 15:56:01 +0100 Subject: update readme --- index.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 9 deletions(-) diff --git a/index.md b/index.md index 4f8a08a..eb78285 100644 --- a/index.md +++ b/index.md @@ -4,21 +4,60 @@ title: "About" # Markdown course website example / template -This is an example of course website, divided into two parts: lectures and -exercises sheets. +This is an example of course website written in Markdown. -Everything is generated from Markdown source files into static files which can -then be served through by any web server. +Inputs: -For convenience, the compilation and deployment can be automated through GitLab -CI or equivalent, which allows automatic publication of the latest version -after pushing the sources to a version-controlled repository for example. +* Markdown files for both the slides and exercises sheets, all pushed in a + private git repository. +Outputs: -## Resources and references +* A public website with flattened slides and exercises sheets without the + solutions, for the students. + +* A private website with the solutions to the exercises, for the teaching + staff. + +* PDF Beamer presentations for the lectures. + +* PDF exercise sheets, with and without solutions, for printing for work + sessions without a computer. + + +## Links + +- Deployed site: + + +- Source repository: + + + +## Behind the scene + +Pandoc is the engine used to process and compile the Markdown source files into +HTML and PDF through LaTeX. This engine allows easy transformation of the +Abstract Syntax Tree of the processed documents, which is used to strip the +solutions from the public exercises sheets for example. + +Quarto is used to generate the website with page navigation and search. Its +more advanced features such as code execution aren't used here. + +Nix is used to manage the build process and its dependencies. Everything is run +within a controlled sandbox, which can be run locally or remotely in a +reproducible manner. + +The GitLab platform is used to host the git source repository. The website and +PDFs are automatically built for each push through GitLab CI. The website in +particular is hosted and published, and updated automatically using GitLab +Pages. + + +## References - [Markdown syntax](https://daringfireball.net/projects/markdown/syntax) -- [Quarto (reference)](https://quarto.org/docs/reference/index.html) - [Pandoc (manual)](https://pandoc.org/MANUAL.html) +- [Quarto (reference)](https://quarto.org/docs/reference/index.html) - [Nix guides](https://nixos.org/learn.html) - [GitLab CI configuration reference](https://docs.gitlab.com/ee/ci/yaml/) -- cgit v1.2.3