From 07b8b8aaddd9e4fa369a59f38b06e6359c56028e Mon Sep 17 00:00:00 2001 From: Joonas Somero Date: Wed, 7 May 2025 12:59:25 +0300 Subject: [PATCH 01/10] Initialize docs/ --- README.md | 5 +++++ docs/index.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+) create mode 100644 docs/index.md diff --git a/README.md b/README.md index 5ad24e61695e..90d1460041d9 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ ## Site rewrite +### Developer documentation + +See [docs/index.md](docs/index.md). + + ### Tools - (`asdf` for runtime version management) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000000..8c48bb82da55 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,54 @@ +# Developer documentation + +## Build environment + +For Matomo web analytics, the build environment needs to have the following variables defined. + +- `MATOMO_URL=${matomo_instance_url}` +- `MATOMO_TAG_MANAGER_CONTAINER=${matomo_tag_manager_container_id}` + + +## Configuration files + +- **ASDF** ([_.tool-versions_](../.tool-versions)) + - **Ruby** ([_Gemfile_](../Gemfile)) + - **Jekyll** ([_\_config.yml_](../_config.yml)) + - **npm** ([_package.json_](../package.json)) + - **webpack** ([_webpack.config.js_](../webpack.config.js)) + - **Tailwind CSS** ([_tailwind.config.js_](../tailwind.config.js)) + - **PostCSS** ([_postcss.config.js_](../postcss.config.js)) + + +## Directory structure + +### `content/` + +The `content/` directory holds the Ruby/Jekyll side of the application. + +- `_data/`: ... +- `_drafts/`: ... +- `_events/`: ... +- `_includes/`: ... +- `_layouts/`: ... +- `_publications/`: ... +- `api/`: ... +- `assets/`: ... +- `pages/`: ... +- `404.md`: Markdown source for the HTTP _404 Not Found_ error response page +- `index.md`: Markdown source for the front page +- `properties.css.liquid`: CSS custom properties +- `site.js.liquid`: ... +- `store.js.liquid`: ... + + +### `src/` + +The `src/` directory holds the Node.js/webpack side of the application. + +- `components/`: React components +- `hooks/`: React custom hooks +- `layouts/`: JSX corresponding to the Liquid templates under `content/_layouts/` +- `pages/`: JSX corresponding to the Markdown-defined pages `content/{index, pages/*}.md` +- `stylesheets/` + - `main.css`: The base stylesheet used by Tailwind CSS +- `utils/`: Some JavaScript utility functions From 612affbbdad09db93783897a1fe6308cad88076c Mon Sep 17 00:00:00 2001 From: Joonas Somero Date: Thu, 8 May 2025 15:16:50 +0300 Subject: [PATCH 02/10] Some documentation --- README.md | 99 +++------------------------------------------ docs/build.md | 18 +++++++++ docs/dev_index.md | 5 +++ docs/index.md | 55 +------------------------ docs/install.md | 87 +++++++++++++++++++++++++++++++++++++++ docs/structure.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 218 insertions(+), 147 deletions(-) create mode 100644 docs/build.md create mode 100644 docs/dev_index.md create mode 100644 docs/install.md create mode 100644 docs/structure.md diff --git a/README.md b/README.md index 90d1460041d9..08ecd62b3a62 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,12 @@ # Fork of [FiQCI/fiqci.github.io](https://github.com/FiQCI/fiqci.github.io) repository -## Site rewrite +## Documentation -### Developer documentation +### For content creators -See [docs/index.md](docs/index.md). +See [Documentation](docs/index.md). -### Tools +### For developers -- (`asdf` for runtime version management) - - Ruby - - (Bundler for managing Ruby gems) - - Jekyll - - Node.js - - React - - Tailwind CSS - - Webpack - -Some installation instructions follow. All of the commands shown are to be executed in the repository root. - - -#### Install `asdf` for runtime version management - -Instructions at [Getting Started | asdf](https://asdf-vm.com/guide/getting-started.html). - - -##### Install Ruby and Node.js using `asdf` - -The file `.tool-versions` contains the version numbers for - - Ruby: 3.3.5 - - Node.js: v22.10.0 - -Install the `asdf` plugins (see the respective Git repositories for required dependencies) with - -```bash -asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git -``` - -and - -```bash -asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git -``` - -Then, as instructed in `asdf --help`, - -> ```text -> asdf install Install all the package versions listed -> in the .tool-versions file -> ``` - -the command `asdf install` should install both Ruby and Node.js. It might take a while, though. When the installations are done, check the versions with - -```console -$ ruby --version -ruby 3.3.5 (2024-09-03 revision ef084cc8f4) [x86_64-linux] -``` - -and - -```console -$ node --version -v22.10.0 -``` - - -##### Install the Ruby gems and Node packages - -If not already installed, install Bundler with - -```bash -gem install bundler -``` - -Then, using Bundler, install the Ruby gems defined in the Gemfile - -```bash -bundle install -``` - -Again, you can check the version (of Jekyll this time) with - -```console -$ jekyll --version -jekyll 4.3.4 -``` - -Finally, install the Node packages with the command - -```bash -npm install -``` - - -### Serve with live reload - -The command `npm run watch` starts Tailwind CSS, Webpack and Jekyll concurrently with the source monitored for changes. - -The site should now be ready at `http://localhost:4000`. +See [Developer documentation](docs/dev_index.md). diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 000000000000..92340ac9a30b --- /dev/null +++ b/docs/build.md @@ -0,0 +1,18 @@ +# Building + +After [installing the software dependencies](install.md), you should be ready to build or serve the site from a local development server. + + +## Serve with live reload + +The command `npm run watch` starts Tailwind CSS, Webpack and Jekyll concurrently with the source monitored for changes. + +The site should now be ready at `http://localhost:4000`. + + +## Build environment + +For Matomo web analytics, the build environment needs to have the following variables defined. + +- `MATOMO_URL=${matomo_instance_url}` +- `MATOMO_TAG_MANAGER_CONTAINER=${matomo_tag_manager_container_id}` diff --git a/docs/dev_index.md b/docs/dev_index.md new file mode 100644 index 000000000000..28ef5f87af09 --- /dev/null +++ b/docs/dev_index.md @@ -0,0 +1,5 @@ +# Developer documentation + +- [Description of the structure of the application](structure.md) +- [Installing the software dependencies](install.md) +- [Building the application](build.md) diff --git a/docs/index.md b/docs/index.md index 8c48bb82da55..695677a505e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,54 +1,3 @@ -# Developer documentation +# Documentation -## Build environment - -For Matomo web analytics, the build environment needs to have the following variables defined. - -- `MATOMO_URL=${matomo_instance_url}` -- `MATOMO_TAG_MANAGER_CONTAINER=${matomo_tag_manager_container_id}` - - -## Configuration files - -- **ASDF** ([_.tool-versions_](../.tool-versions)) - - **Ruby** ([_Gemfile_](../Gemfile)) - - **Jekyll** ([_\_config.yml_](../_config.yml)) - - **npm** ([_package.json_](../package.json)) - - **webpack** ([_webpack.config.js_](../webpack.config.js)) - - **Tailwind CSS** ([_tailwind.config.js_](../tailwind.config.js)) - - **PostCSS** ([_postcss.config.js_](../postcss.config.js)) - - -## Directory structure - -### `content/` - -The `content/` directory holds the Ruby/Jekyll side of the application. - -- `_data/`: ... -- `_drafts/`: ... -- `_events/`: ... -- `_includes/`: ... -- `_layouts/`: ... -- `_publications/`: ... -- `api/`: ... -- `assets/`: ... -- `pages/`: ... -- `404.md`: Markdown source for the HTTP _404 Not Found_ error response page -- `index.md`: Markdown source for the front page -- `properties.css.liquid`: CSS custom properties -- `site.js.liquid`: ... -- `store.js.liquid`: ... - - -### `src/` - -The `src/` directory holds the Node.js/webpack side of the application. - -- `components/`: React components -- `hooks/`: React custom hooks -- `layouts/`: JSX corresponding to the Liquid templates under `content/_layouts/` -- `pages/`: JSX corresponding to the Markdown-defined pages `content/{index, pages/*}.md` -- `stylesheets/` - - `main.css`: The base stylesheet used by Tailwind CSS -- `utils/`: Some JavaScript utility functions +- [Description of the structure of the application](structure.md#) diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000000..7e3c35a22b94 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,87 @@ +# Installation + +- `asdf` for runtime version management + - Ruby + - (Bundler for managing Ruby gems) + - Jekyll + - Node.js + - React + - Tailwind CSS + - Webpack + +Some installation instructions follow. All of the commands shown are to be executed in the repository root. + + +## Install `asdf` for runtime version management + +Instructions at [_Getting Started | asdf_](https://asdf-vm.com/guide/getting-started.html). + + +## Install Ruby and Node.js using `asdf` + +The file `.tool-versions` contains the version numbers for + - Ruby: 3.3.5 + - Node.js: v22.10.0 + +Install the `asdf` plugins (see the respective Git repositories for required dependencies) with + +```bash +asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git +``` + +and + +```bash +asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git +``` + +Then, as instructed in `asdf --help`, + +> ```text +> asdf install Install all the package versions listed +> in the .tool-versions file +> ``` + +the command `asdf install` should install both Ruby and Node.js. It might take a while, though. When the installations are done, check the versions with + +```console +$ ruby --version +ruby 3.3.5 (2024-09-03 revision ef084cc8f4) [x86_64-linux] +``` + +and + +```console +$ node --version +v22.10.0 +``` + + +## Install the Ruby gems and Node packages + +If not already installed, install Bundler with + +```bash +gem install bundler +``` + +Then, using Bundler, install the Ruby gems defined in the Gemfile + +```bash +bundle install +``` + +Again, you can check the version (of Jekyll this time) with + +```console +$ jekyll --version +jekyll 4.3.4 +``` + +Finally, install the Node packages with the command + +```bash +npm install +``` + +You should now be able to [serve the site from a local development server](build.md#serve-with-live-reload). diff --git a/docs/structure.md b/docs/structure.md new file mode 100644 index 000000000000..5e5159cd6b30 --- /dev/null +++ b/docs/structure.md @@ -0,0 +1,101 @@ +# Structure + +## Configuration files + +- **ASDF** ([_.tool-versions_](../.tool-versions)): Version numbers for Ruby and Node.js runtimes. + - **Ruby** ([_Gemfile_](../Gemfile)): The required Ruby gems. + - **Jekyll** ([_\_config.yml_](../_config.yml)): Jekyll configuration file. + - **npm** ([_package.json_](../package.json)): Node.js package configuration. + - **webpack** ([_webpack.config.js_](../webpack.config.js)): Webpack configuration. + - **Tailwind CSS** ([_tailwind.config.js_](../tailwind.config.js)): Tailwind CSS configuration. + - **PostCSS** ([_postcss.config.js_](../postcss.config.js)): PostCSS configuration. + + +## Directory structure + +### `content/`: Ruby/Jekyll + +- `_data/`: Directory for [Jekyll data files](https://jekyllrb.com/docs/datafiles/). + - `theme/`: + - `constants.yml`: The constants used in the site theme. +- `_drafts/`: Directory for [Jekyll draft posts](https://jekyllrb.com/docs/posts/#drafts). +- `_events/`: Contains the 'events' collection configured in [_config.yml](../_config.yml). +- `_includes/`: Directory for [Jekyll includes](https://jekyllrb.com/docs/includes/), i.e. Liquid template fragments that can be included in content or templates. + - `external/`: Links to software libraries served from CDNs. + - `font.html`: The [Inter font](https://github.com/rsms/inter) used on the site. + - `mathjax.html`: [MathJax](https://www.mathjax.org/) for rendering math. +- `_layouts/`: Directory for [Jekyll layouts](https://jekyllrb.com/docs/layouts/), i.e. layout Liquid templates. + - `base.html`: The base template. + - `home.html`: The template for the home page. + - `page.html`: A page template. + - `post.html`: A post template. +- `_publications/`: Contains the 'publications' collection configured in [_config.yml](../_config.yml). +- `api/`: Directory for templates to be rendered and served as JSON. + - `theme/` + - `constants.yml`: Liquid template for serving _/content/\_data/theme/constants.yml_ at _/api/theme/constants.json_. +- `assets/`: Directory for static assets, such as images. +- `pages/`: Markdown sources for individual pages. + - `about.md`: \[TODO\] + - `access.md`: \[TODO\] + - `events.md` The 'Events' page. + - `home.md`: The home page. (Rendered as _/index.html_.) + - `publications.md`: The 'Blogs and instructions' page. + - `search.md`: The search results page. + - `status.md`: The 'Status' page. +- `404.md`: Markdown source for the HTTP _404 Not Found_ error response page. +- `properties.css.liquid`: CSS custom properties. +- `site.js.liquid`: \[TODO\] +- `store.js.liquid`: \[TODO\] + + +### `src/`: Node.js/React + +- `components/`: React components. +- `hooks/`: React custom hooks. +- `layouts/`: JSX corresponding to the Liquid templates found under _/content/\_layouts/_. +- `pages/`: JSX corresponding to the Markdown-defined pages under _/content/pages/_. +- `stylesheets/` + - `main.css`: The base stylesheet used by Tailwind CSS. +- `utils/`: Some JavaScript utility functions. + + +## Overview: Home page + +- _Home_ + - **Page Markdown** [home.md](../content/pages/home.md) + - `id='access-cards'` + - `id='blog-cards'` + - `id='event-cards'` + - **Page JSX** [home.md.jsx](../src/pages/home.md.jsx) + - `` (_props_ <-- `useJsonApi()`) + - `` (createPortal `id='access-cards'`) + - `` (createPortal `id='blog-cards'`) + - `` (createPortal `id='event-cards'`) + - **`` (createRoot `id='react-root'`)** + - **Liquid layout** [home.html](../content/_layouts/home.html) + - `id='hero'` + - `id='about-fiqci'` + - **Liquid layout** [base.html](../content/_layouts/base.html) + - **`id='react-root'`** + - `id='navigation-header'` + - `id='footer'` + - **Layout JSX** [home.html.jsx](../src/layouts/home.html.jsx) + - `` (_props_ <-- ``) + - `` (createPortal `id='hero'`) + - `` (createPortal `id='about-fiqci'`) + - **Layout JSX** [base.html.jsx](../src/layouts/base.html.jsx) + - `` + - `` (createPortal `id='navigation-header'`) + - `