update readme

1 files 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:
+  <https://pacien.gitpages.univ-eiffel.fr/markdown-course-website>
+
+- Source repository:
+  <https://gitlab.univ-eiffel.fr/pacien/markdown-course-website>
+
+
+## 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/)