From a4fc2ad980f6663b6b3735bec58b0caa0797d3e3 Mon Sep 17 00:00:00 2001 From: MuhammadAashirAslam Date: Mon, 10 Aug 2026 09:23:30 +0500 Subject: [PATCH] Update Hugo content documentation --- README.md | 154 +++++++++++----------- content/docs/docs-meta/common-issues.md | 61 +++++++-- content/docs/docs-meta/overview.md | 167 ++++++++++++------------ content/docs/docs-meta/search.md | 103 ++++++--------- 4 files changed, 249 insertions(+), 236 deletions(-) diff --git a/README.md b/README.md index 142cb99ebf5..b50b5b761bb 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,113 @@ -# preCICE Webpage - [precice.org](https://precice.org/) +# preCICE website - [precice.org](https://precice.org/) ## Local development -First install [`pre-commit`](https://repology.org/project/python:pre-commit/versions) to keep your commits clean. +First install [pre-commit](https://pre-commit.com/) using its +[installation instructions](https://pre-commit.com/#install) to keep commits +clean. -The website is using [Jekyll](https://jekyllrb.com/) static website generator and [Github pages](https://pages.github.com/). -To run and develop it locally you need to install [`rbenv`](rbenv.org) using `apt install rbenv ruby-build`. -Then use `rbenv init` and follow the instructions to set it up. -With `rbenv` installed and activated in your shell: +The website uses the [Hugo](https://gohugo.io/) static site generator and +[GitHub Pages](https://pages.github.com/). Install Hugo Extended and Go using +the versions configured in the GitHub Actions workflows. Follow Hugo's +[installation guide](https://gohugo.io/installation/) and Go's +[installation guide](https://go.dev/doc/install); Hugo Extended is required for +the site's asset pipeline. Hugo Modules require Git and Go, as described in the +[Hugo Modules documentation](https://gohugo.io/hugo-modules/use-modules/). Node.js +is only needed when working on Algolia search. + +After installation, check the tools before building: ```bash -git clone --recurse-submodules https://github.com/precice/precice.github.io && cd precice.github.io -pre-commit install -rbenv install -bundle install -bundle exec jekyll serve -l +hugo version +go version +pre-commit --version ``` -You can now view website locally in your browser at `localhost:4000`. +```bash +git clone https://github.com/precice/precice.github.io.git +cd precice.github.io +pre-commit install +hugo server +``` -## Update submodules +You can now view the website locally at . On the first +build, Hugo downloads the module versions recorded in `go.mod`. No Ruby or Git +submodule setup is required. -Submodules do not yet get updated automatically. This means if you change something in the OpenFOAM adapter documentation or the description of the tutorials, you need to explicitly trigger an update here: +Before opening a pull request, run the production build: ```bash -git submodule update --remote --merge +hugo mod verify +hugo --gc --minify --cleanDestinationDir --environment production +pre-commit run --all-files ``` -This updates **all** submodules. You can call it from everywhere (you do not need to `cd` into the submodule). -Afterwards, commit and push. +## Update imported documentation -Do not directly edit the content of the submodules from within the website repository. This might give ugly merge conflicts. +Adapter, tutorial, and tooling documentation is included through Hugo Modules. +The `Update Hugo modules` workflow checks the upstream repositories daily and +records the selected revisions in `go.mod` and `go.sum`. -## Pull with submodules - -To pull changes including submodules +To update the imported documentation locally, run: ```bash -git pull --recurse-submodules +python3 tools/sync_hugo_modules.py ``` -## Build inside a Docker container +Review and commit the resulting `go.mod` and `go.sum` changes. Do not edit +downloaded module files from this repository; make documentation changes in the +repository that owns them. -Instead of building on your system (which requires some setup the first time), you can directly serve the website from a Docker container (using the community image [`jekyll/jekyll`](https://hub.docker.com/r/jekyll/jekyll)). In this directory, after you initialize and update the git submodules, run the following: +Adding a new imported project requires an import and mounts in +`config/_default/module.toml`, an edit-link mapping in the Hugo configuration, +and a navigation entry where appropriate. Adding a tutorial currently also +requires an entry in `data/sidebars/tutorial_sidebar.yml`. -```shell -docker run --rm --volume="$PWD:/srv/jekyll:Z" --publish 127.0.0.1:4000:4000 -it jekyll/jekyll jekyll serve -``` +## Search + +Hugo writes the search export to `public/algolia.json`. Validate the generated +records without uploading them with: -Arguments: +```bash +npm ci +npm run test:algolia +hugo --gc --minify --cleanDestinationDir --environment production +npm run algolia:index -- --dry-run +``` -* `docker run`: The Docker command to run a container from an existing image -* `--rm`: Automatically remove (or not) the container when it exists -* `--volume`: Mount the current directory (`$PWD`) to a directory in the container (`/srv/jekyll`), so that only the current container can see the content (`:Z`) -* `--publish`: Publish the container's port 4000 (where Jekyll serves the website) to the host port 4000. Note that `127.0.0.1` is the localhost in IPv4. For IPv6, you can replace that with `[::1]`. -* `-it`: Interactive container, capturing signals (such as `Ctrl-C`). -* `jekyll/jekyll`: The image -* `jekyll serve`: The command to run. Somehow, the current default `make` target does not work in this context. +See [the search documentation](docs/algolia.md) for test-index and credential +setup. ## Further information -If you would like to learn more about the preCICE documentation, a good start are the [documentation of the documentation pages](https://precice.org/docs-meta-overview.html). +The [documentation of the documentation pages](https://precice.org/docs-meta-overview.html) +explains the website structure, navigation, front matter, and imported content. ## Changing the news banner -Edit [`_includes/news_banner.html`](_includes/news_banner.html). - -A good starting point is the following: - -```html - -``` - -Use the following to selectively change appearance. - -```html -{% if include.landing %} - Displayed on the landing page. -{% else %} - Displayed on other pages. -{% endif %} -``` +Edit [`layouts/partials/news_banner.html`](layouts/partials/news_banner.html). +The partial explains how to enable or disable the banner, change its text and +link, and choose whether it appears on the landing page or on other pages. ## Common issues while building the site -* If you get permission issues to install gems, resist the impulse of `sudo`: you can install the dependencies locally by running `bundle config set --local path 'vendor/bundle'` before `bundle install`. - -* If you get errors like `Gem::Ext::BuildError: ERROR: Failed to build gem native extension.` or `mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h`, then (as the error message suggests), you may need to install a Ruby development environment (e.g., `ruby-dev`). - -* If you are a poor soul that is stuck developing on Windows, the `-l` flag is known to crash, so best try without. - -* Should you get the warning - - ```bash - Fetching citation data failed with OpenURI::HTTPError - ``` - - while building the site locally, then you have been rate limited by Google Scholar. The citation database won't be up to date. Alternatively open [http://scholar.google.com/](http://scholar.google.com/) in a browser and complete the Captcha. +- If Hugo cannot download a module, first check that Git and Go are installed, + then run `hugo mod verify`. A fresh clone needs network access to download the + versions recorded in `go.mod`. +- If Hugo reports a checksum mismatch, do not disable verification. The upstream + source or selected revision has changed; update the module through the normal + synchronization process and review the resulting `go.mod` and `go.sum` files. +- If a container or restricted environment cannot clean Hugo's cache, build + with a writable cache directory, for example + `HUGO_CACHEDIR=/tmp/precice-hugo-cache hugo --gc --minify`. +- If search results are stale, remember that a Hugo build only writes + `public/algolia.json`; the Algolia indexing workflow or CLI must upload it. -For further information see the [documentation page on common issues](https://precice.org/docs-meta-common-issues.html). +For further information, see [common issues](https://precice.org/docs-meta-common-issues.html). ## Licenses -The content of the preCICE webpage is licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.en). Third-party licenses (e.g. of the framework we use) are collected in the `licenses` subfolder. Note that preCICE itself has a software license, [LGPL v3](https://www.gnu.org/licenses/lgpl-3.0.en.html). +The content of the preCICE webpage is licensed under +[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.en). Third-party +licenses are collected in the `licenses` subfolder. preCICE itself is licensed +under [LGPL v3](https://www.gnu.org/licenses/lgpl-3.0.en.html). diff --git a/content/docs/docs-meta/common-issues.md b/content/docs/docs-meta/common-issues.md index 15def59bd99..f48c9130b09 100644 --- a/content/docs/docs-meta/common-issues.md +++ b/content/docs/docs-meta/common-issues.md @@ -1,26 +1,63 @@ --- -title: Troubleshooting and Common Issues +title: Troubleshooting and common issues permalink: docs-meta-common-issues.html -keywords: issues, troubleshooting, bugs, errors, warnings, documentation, jekyll, build locally -summary: +aliases: + - /docs-meta-common-issues.html +keywords: issues, troubleshooting, Hugo, modules, build locally +summary: "Solutions for common local Hugo and module build problems." --- -## Jekyll error '429 Too Many Requests' +## Hugo cannot download a module -When building the site locally in frequent succession, Jekyll might complain in the following way: +Hugo Modules require Git and Go. A fresh clone downloads the versions recorded +in `go.mod` when Hugo first builds the site, so it also requires network access. +Check the local tools and verify the configured modules with: ```bash - open-uri.rb:364:in `open_http': 429 Too Many Requests (OpenURI::HTTPError) +git --version +go version +hugo mod verify ``` -### Cause +## Hugo reports a checksum mismatch -In order to retrieve the current number of citations on Google Scholar, we use the `nokogiri` gem to scrape [http://scholar.google.com/scholar?hl=en&cites=5053469347483527186](http://scholar.google.com/scholar?hl=en&cites=5053469347483527186) and extract the number of citations (for more information see `_plugins/googlescholar.rb`). Frequent scraping attempts can hit Google's rate limit and lead to a soft IP ban. +If an upstream repository changes a revision that was already downloaded, Go +will reject it because its content no longer matches the checksum in `go.sum`. +Do not disable checksum verification. Instead, synchronize the affected module +revision, review the resulting `go.mod` and `go.sum` changes, and commit them +together: -### Solution +```bash +python3 tools/sync_hugo_modules.py +hugo mod verify +``` + +## Local imported content is older than upstream content + +Hugo builds imported documentation from the revisions pinned in `go.mod`, not +from another checkout on your computer. Run the `Update Hugo modules` workflow +or the synchronization command above to select newer upstream revisions. + +## Hugo cannot clean its cache + +The production build uses `--gc`, which requires a writable Hugo cache. In a +restricted container or environment, select a cache directory owned by your +user: -Either visit [http://scholar.google.com](http://scholar.google.com) in your browser and solve the Captcha or deactivate the `googlescholar.rb` plugin temporarily, e.g. by renaming it to `googlescholar.rb_`, or commenting out its contents. +```bash +HUGO_CACHEDIR=/tmp/precice-hugo-cache hugo --gc --minify +``` + +## Search results are stale -## Jekyll crashes on Windows +Building the site only creates `public/algolia.json`; it does not upload records +to Algolia. Build and validate the export locally with: + +```bash +npm ci +hugo --gc --minify --cleanDestinationDir --environment production +npm run algolia:index -- --dry-run +``` -Some of the flags (arguments) for running `jekyll build` or `jekyll serve` are known to crash on Windows, e.g. `--safe -l` or `--detach`. In most cases there is no workaround, because the features are simply not implemented or available in Windows, so run the command without the flag. +Use the `Update the Algolia search index` workflow to publish the validated +records with the repository's configured credentials. diff --git a/content/docs/docs-meta/overview.md b/content/docs/docs-meta/overview.md index 86e40fef27e..916c87e6845 100644 --- a/content/docs/docs-meta/overview.md +++ b/content/docs/docs-meta/overview.md @@ -1,151 +1,146 @@ --- title: Documentation of the documentation -keywords: pages, authoring, exclusion, frontmatter -summary: "This page is an introduction to the development of the preCICE documentation, based on a jekyll theme called documentation-theme-jekyll. You will learn how to run jekyll locally, about the sidebar structure, how to name and where to save documentation pages and what a minimal frontmatter looks like." +keywords: pages, authoring, front matter, Hugo, modules +summary: "An introduction to developing the preCICE documentation with Hugo: local builds, navigation, page structure, front matter, and imported content." permalink: docs-meta-overview.html +aliases: + - /docs-meta-overview.html --- ## About the content -This majority of this documentation focuses on the technical side of writing content. See [our content guidelines](docs-meta-content-guidelines.html) to learn what the content should look like. +Most of this documentation focuses on the technical side of writing content. +See the [content guidelines](docs-meta-content-guidelines.html) to learn what +the content should look like. -## About the theme +## About the website -This site is based on a jekyll theme by technical writer Tom Joht called [documentation-theme-jekyll](https://github.com/tomjoht/documentation-theme-jekyll). At the time of writing this theme was the second most popular documentation-style jekyll theme on [jamstackthemes.dev](https://jamstackthemes.dev/#ssg=jekyll) and has been selected for its rich feature set and clean, functional design out of the box. - -In addition Tom did a great job documenting the theme (using the theme) and you can read about specific features and their implementation and use [in his documentation](https://idratherbewriting.com/documentation-theme-jekyll/index.html). +The website is built with [Hugo](https://gohugo.io/). Website-owned Markdown +pages live in `content/`, navigation data lives in `data/sidebars/`, and shared +templates live in `layouts/`. Hugo combines these with static files and +documentation imported from other preCICE repositories. ## Getting started -To develop the website locally it is recommended to install jekyll and run +Install Hugo Extended and Go using the versions listed in the repository +`README.md`, then run: ```bash -bundle exec jekyll serve +hugo server ``` -The [theme's documentation page](https://idratherbewriting.com/documentation-theme-jekyll/index.html#2-install-jekyll) has a step-by-step guide to install jekyll and the plugin ("gem") manager `bundler`. When running jekyll for the first time you might have to install and/or update the gems first: +Open . Hugo watches local files and rebuilds the site +when they change. On the first run, it downloads the module versions recorded +in `go.mod`. + +Before opening a pull request, use the production build: ```bash -bundle install -bundle update +hugo mod verify +hugo --gc --minify --cleanDestinationDir --environment production ``` -Now try again `bundle exec jekyll serve` and the site should be running at `http://localhost:4000/`. Jekyll will refresh and rebuild when you change files. - -## How documentation-theme-jekyll works in a nutshell +## How the website works in a nutshell -The two main ingredients behind this jekyll theme are +The two main ingredients behind the website are: -1. **The sidebar**, i.e. the navigation tree. Jekyll builds the sidebar based on the `sidebar.yml` in the `_data/sidebars` directory. The YAML contains the relative structure of the navigation tree as well as the links to the html pages. -2. **A set of pages**, i.e. Markdown or html files. Jekyll parses the Markdown or html files in the `pages` directory, renders them to html (in case of Markdown), and places them in the root folder. +1. **The sidebar**, the navigation tree. The sidebar partial renders the YAML + files in `data/sidebars/` into the navigation shown on each page. +2. **A set of pages**, Markdown files in `content/` and mounted Markdown files + from imported repositories. Hugo renders them to HTML using the templates in + `layouts/`. ### Sidebar -Here is a snippet from the `_data\sidebars\docs_sidebar.yml` that spans (the maximum) two levels: +The sidebar data retains the established three-level structure. For example, +the following excerpt from `data/sidebars/docs_sidebar.yml` represents a page +with nested pages: ```yaml entries: - title: sidebar - product: Docs - version: 2.1.0 + product: Documentation folders: - - title: Configuration - output: web, pdf folderitems: - - title: Basics url: /configuration-introduction.html - output: web, pdf - subfolders: - - title: Coupling Scheme - output: web, pdf + - title: Coupling scheme subfolderitems: - - title: Overview url: /configuration-coupling.html - output: web, pdf - - - title: Multi Coupling - url: /configuration-coupling-multi.html - output: web, pdf - - - title: Acceleration - url: /configuration-acceleration.html - output: web, pdf ``` +The `url` of each entry must match the rendered page URL. Keep the established +`.html` URLs when moving an existing page, and use an alias when a page URL must +change. + ### Where to save files -Save Markdown files in the `pages` directory in an appropriate subdirectory. Jekyll is agnostic to this folder structure - subdirectories are for human ease of organisation only. +Save website-owned Markdown files below `content/` in the section that owns +them. Unlike Jekyll, the directory structure is meaningful to Hugo: a directory +containing `_index.md` is a section and its path contributes to page URLs. ```text -pages -|_ docs - |_ configuration - |_ configuration-introduction.html - |_ ... - |_ installation - |_ ... +content/ +└── docs/ + └── configuration/ + └── basics/ + └── introduction.md ``` ### Naming conventions -{% important %} -Because of the flat hierarchy files have to be named uniquely. -{% endimportant %} - -This can be easily achieved by baking in the category/topic into the filename and adds some welcome robustness, e.g. +Hugo derives URLs from content paths, so file names no longer need to be unique +across the complete documentation tree. Use descriptive, lower-case file names +with hyphens instead of underscores, for example +`configuration-introduction.md`. Use the singular form where it reads +naturally. Preserve an existing public URL with `permalink` or `aliases` when a +file is moved. -```text -docs -|_ configuration - |_ configuration-introduction.html - |_ configuration-coupling.html - |_ configuration-coupling-multi.html -``` - -File names should contain hyphens `-` instead of underscores `_` following best practices for [SEO](https://support.google.com/webmasters/answer/76329?hl=en). +### Minimal viable front matter -In addition use the singular form where possible, e.g. `configration-action.html` instead of `configuration-actions.html`. - -### Minimal viable frontmatter - -The minimal frontmatter contains only the options `title` and `permalink` (required) but should be complemented by `keywords` and `summary` (optional). +Every page needs a title. Existing pages should retain their `permalink` to +preserve public URLs; new pages usually derive their URL from their path. Add +keywords and a summary where they improve search and page metadata. ```yaml --- -title: Configuration Basics +title: Configuration basics permalink: configuration-introduction.html keywords: configuration, basics, overview -summary: "preCICE needs to be configured at runtime via an `xml` file, typically named `precice-config.xml`. Here, you specify which solvers participate in the coupled simulation, which coupling data values they exchange, which numerical methods are used for the data mapping and the fixed-point acceleration and many other things. " +summary: "Configure participants, meshes, exchanged data, mappings, and coupling schemes." --- ``` -The `permalink` has to be the full file name ending in `.html` with no leading slash `\`. During the build process jekyll processes the frontmatter and places the file at `permalink` value, i.e. in the root directory (by default is `_site`). +Use `aliases` for additional legacy URLs: -## Rendering content from external repositories - -While the main content of this website is sourced from the same [repository](https://github.com/precice/precice.github.io) that hosts the mechanics of it, some content is sourced from separate repositories. The main reason is to keep the documentation next to the respective code, so that developers can view it without looking at the website and update it in the same contribution, while users can find everything in the same place. Read more about this concept in the [preCICE v2 reference paper](https://doi.org/10.12688/openreseurope.14445.2). This practice is not yet uniformly adopted, but we are working on migrating more content. - -External repositories are included as Git submodules, specified in the [`.gitmodules`](https://github.com/precice/precice.github.io/blob/master/.gitmodules) file. One example is the [tutorials](tutorials), which is covered by [additional documentation for adding new tutorials](https://precice.org/community-contribute-to-precice.html#adding-a-new-tutorial-to-the-website). +```yaml +aliases: + - /configuration-introduction.html +``` -To fetch content from an external repository/project (replace the `my-*` with the actual names): +The [documentation cheatsheet](docs-meta-cheatsheet.html) lists supported front +matter fields and Hugo shortcodes. -1. Switch to a new branch of the website and specify the new module: `git submodule add https://github.com/precice/my-project imported/my-project`. -2. Set the branch to track, if not the default: `git submodule set-branch --branch my-branch imported/my-project`. This is particularly useful in case you are adding new documentation via a pull request. However, remember to reset the branch after merging. -3. The above commands should have modified the `.gitmodules` file and staged changes. Commit the result (remember to push later, after testing). -4. Update all submodules with `git submodule update --remote --merge`. If successful, you should see your new project in the `imported/` directory. Remember that the branch in your external project must already be published. -5. Update the commit that the module points to: `git add imported/my-project && git commit -m "Update my-project submodule" && git push`. You should only see a `modified: imported/my-project (new commits)` in your `git status`, not the files of that directory. -6. In your GitHub pull request to the website, at the "files changed" view, you should see a submodule with a Git reference to your new project in the `imported/` directory. +## Rendering content from external repositories -To render the fetched content on the website: +Some website content is maintained in the repository that owns the related +adapter, tutorial, or tool. This keeps documentation close to the code while +presenting it in one place on the website. Hugo Modules mount that source +content into the website's content tree. -1. In the file [`_config.yml`](https://github.com/precice/precice.github.io/blob/master/_config.yml), specify the newly imported directory in the list of `subprojects:`. -2. In the same file, add an entry under the `defaults:` list, associating the subproject with some layout, sidebar, a path for the "Edit me" button, and more features. -3. Remember to make the new pages discoverable, e.g., by adding them to some [sidebar](https://github.com/precice/precice.github.io/tree/master/_data/sidebars), or linking from another page. +To add a new imported project: -After you merge the pull request in the external repository, remember to change the branch in the submodule (step 2) and in the `_config.yml` (step 1). If you squash-and-merge the pull request, the commit you were pointing to will not exist anymore. The easiest workaround it to delete the `imported/my-project` folder and update the submodules again (remember to add, commit, and push). You can always check the `git diff` for the commit it will point the submodule to. +1. Add its module import and mounts in `config/_default/module.toml`, and add + the corresponding edit-link mapping in the Hugo configuration. +2. Run `hugo mod get github.com/precice/my-project@`. +3. Run `hugo mod tidy` and `hugo mod verify`. +4. Add the rendered pages to the appropriate sidebar when needed. +5. Build the site and verify page URLs, edit links, and last-modified dates. -To update the content, push to your repository and then [manually trigger the "update submodules" workflow](https://github.com/precice/precice.github.io/actions/workflows/update-submodules.yml). Alternatively, add a GitHub Actions workflows to your repository, to [update the website automatically](https://github.com/precice/tutorials/blob/master/.github/workflows/update-website.yml). You will need to [share the `WORKFLOW_DISPATCH_TOKEN` with the external repository](https://github.com/organizations/precice/settings/secrets/actions). +The `Update Hugo modules` workflow checks the imported repositories and updates +their selected revisions in `go.mod` and `go.sum`. Do not copy imported content +into this repository or edit the downloaded module cache. Make content changes +upstream, then update the recorded module revision. diff --git a/content/docs/docs-meta/search.md b/content/docs/docs-meta/search.md index 2ca258c089f..cb369a31e6a 100644 --- a/content/docs/docs-meta/search.md +++ b/content/docs/docs-meta/search.md @@ -1,84 +1,67 @@ --- title: Update the search index keywords: search, Algolia, search index, update search index -summary: +summary: "Build, validate, and publish the Hugo-generated Algolia search index." permalink: docs-meta-search.html +aliases: + - /docs-meta-search.html --- ## Overview -Our search is powered by Algolia, using their [free community plan](https://www.algolia.com/pricing/). Algolia conveniently provides the `jekyll-algolia` gem at [https://github.com/algolia/jekyll-algolia](https://github.com/algolia/jekyll-algolia) for a smooth integration with jekyll. +The website search is powered by [Algolia](https://www.algolia.com/). Hugo +generates `public/algolia.json` from rendered page content, and the Node.js CLI +in `tools/algolia-index.mjs` converts that export into Algolia records and +atomically replaces the configured index. This replaces the former +`jekyll-algolia` plugin. ## Configuring search -In `_config.yml` the `algolia-jekyll` gem is configured as follows: +The public frontend settings are configured under `[params.algolia]` in +`config/_default/hugo.toml`: -```yaml -algolia: - application_id: XXX - index_name: XXX - search_only_api_key: XXX - nodes_to_index: 'p,code,table' +```toml +[params.algolia] +application_id = "your-application-id" +index_name = "your-index-name" +search_only_api_key = "your-search-only-key" +nodes_to_index = "p,code,table" +max_record_size = 20000 ``` -Of note is the last entry `nodes_to_index` that determines which HTML tags will be indexed. - -There is an upper limit on how much information one such node, e.g. the content of a `` block, may contain. In rare cases extra long `` blocks may have to be broken up into several ones. +`nodes_to_index` controls which rendered HTML elements become search records. +`max_record_size` is the maximum serialized record size accepted by the target +Algolia plan; the indexer validates and splits records as needed. The +search-only key is visible in the browser and must be restricted to search +access. Never commit an indexing key. ## Updating the index -The `jekyll-algolia` gem makes updating the index a breeze. Simply change into the root directory and execute: +First install the Node.js dependencies and build the Hugo export: ```bash -ALGOLIA_API_KEY='XXX' bundle exec jekyll algolia +npm ci +npm run test:algolia +hugo --gc --minify --cleanDestinationDir --environment production +npm run algolia:index -- --dry-run ``` -Result: - -```text -Configuration file: E:/code/precice.github.io_new/_config.yml -Processing site... - Subproject: imported/tutorials/quickstart - Adding pages: README.md - Subproject: imported/tutorials/elastic-tube-1d - Adding pages: README.md - Subproject: imported/tutorials/elastic-tube-3d - Adding pages: README.md - Subproject: imported/tutorials/flow-over-heated-plate - Adding pages: README.md - Subproject: imported/tutorials/flow-over-heated-plate-steady-state - Adding pages: README.md - Subproject: imported/tutorials/flow-over-heated-plate-nearest-projection - Adding pages: README.md - Subproject: imported/tutorials/heat-exchanger - Adding pages: README.md - Subproject: imported/tutorials/multiple-perpendicular-flaps - Adding pages: README.md - Subproject: imported/tutorials/partitioned-elastic-beam - Adding pages: README.md - Subproject: imported/tutorials/partitioned-heat-conduction - Adding pages: README.md - Subproject: imported/tutorials/partitioned-heat-conduction-complex - Adding pages: README.md - Subproject: imported/tutorials/perpendicular-flap - Adding pages: README.md - Subproject: imported/tutorials/turek-hron-fsi3 - Adding pages: README.md - Subproject: imported/tutorials/partitioned-pipe - Adding pages: README.md - Subproject: imported/openfoam-adapter/docs - Adding pages: config.md, extend.md, get.md, openfoam-support.md, README.md - -Progress: |====================================================================| +The dry run validates the JSON schema, configured selector, record sizes, and +resulting records without contacting Algolia. To publish after that validation, +provide a restricted indexing key in the environment: -Progress: |==========================================Settings are already up todate. -Getting list of existing records -Updating records in index jekyll... -Records to delete: 1582 -Records to add: 1718 - -Progress: |====================================================================| -✔ Indexing complete +```bash +export ALGOLIA_APP_ID="your-application-id" +export ALGOLIA_WRITE_API_KEY="your-restricted-indexing-key" +export ALGOLIA_INDEX_NAME="your-index-name" +npm run algolia:index ``` -Be aware, that updates to the index count towards the limit of free operations, so it is recommended to update once a month. +The indexing key needs `addObject`, `deleteIndex`, and `editSettings` +permissions, and its index restriction must include the temporary index prefix +used for atomic replacement. Production updates run through the `Update the +Algolia search index` workflow, which reads these values from repository +secrets. + +See [`docs/algolia.md`](https://github.com/precice/precice.github.io/blob/hugo/docs/algolia.md) +for complete dashboard, test-index, and query-validation instructions.