Update instructions for adding new apps pages (#2622)

* Update instructions for adding new apps pages!

* toc

Author: rkronberg

CONTRIBUTING.md

@@ -58,7 +58,8 @@ must use pull requests.
  - Create your own branch from master (or work in an already existing branch, if agreed)
  - Create / bring there the content you want to work with. Pay attention to file naming!
  - Make sure the data is 100% correct (no Taito or other old references, language is correct, commands work, style is same as in other articles)
- - When creating a new article, add it also to the mkdocs.yml navigation OR in the index.md file in that folder (in case of FAQs for example). For new software (=apps) pages, add them to by_discipline.md. **Do not** manually edit by_license.md or index.md files under apps since these are automatically generated. See also the [FAQ](FAQ.md#how-to-include-my-new-page-in-the-navigation-panel).
+ - When creating a new article, add it also to the mkdocs.yml navigation OR in the index.md file in that folder (in case of FAQs for example). See also the [FAQ](FAQ.md#how-to-include-my-new-page-in-the-navigation-panel).
+    - For new software (Applications) pages, see [this FAQ entry](FAQ.md#how-do-i-add-a-new-applications-page) on how to include them on the Applications index pages. **Do not edit these index pages by hand!**
  - Make a pull request for your work to be added to Master
     - Look at the test results of your PR: if they are red, check what's wrong and commit to the PR directly to fix it. See the [FAQ](FAQ.md#my-pr-did-not-pass-the-tests-what-to-do) for instructions.
     - Assign one or more reviewers, try to choose someone who knows the _content_. See also the [FAQ](FAQ.md#how-and-who-should-i-ask-to-review-my-pr).

FAQ.md

@@ -22,13 +22,13 @@ The [contributing guide](CONTRIBUTING.md) outlines the basic steps of starting c
   - [Which Markdown features/extensions are available?](#which-markdown-featuresextensions-are-available)
   - [How do I add definitions to the glossary / display definitions as tooltips?](#how-do-i-add-definitions-to-the-glossary--display-definitions-as-tooltips)
   - [How do I use the announcement bar?](#how-do-i-use-the-announcement-bar)
+  - [How do I include a new software page on the "Applications" index pages](#how-do-i-add-a-new-applications-page)
   - [How do I add a license tag to an application page?](#how-do-I-add-a-license-tag-to-an-application-page)
   - [How do I tag an application as available under a web interface?](#how-do-i-tag-an-application-as-available-under-a-web-interface)
   - [How do I make footnotes?](#how-do-i-make-footnotes)
   - [How do I improve search results?](#how-do-i-improve-search-results)
   - [How do I redirect incoming links](#how-do-i-redirect-incoming-links)
 
-
 ## How to include my new page in the navigation panel?
 
 If you add a new page that you want to appear in the left-hand-side navigation panel, you need to edit the `mkdocs.yml` file in the root of the repository. Items appearing in the navigation panel are listed in this file as key/value pairs under the `nav:` key, for example:
@@ -353,6 +353,66 @@ Make sure to "un-uncomment" every other line, since only a single line may be in
 
 Documentation for _Material for MkDocs_ has a [search feature](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/?h=icon#search) including **previews** for the icon database. The path of the icon file can be determined by examining the shortcode. For example, the path `.icons/material/information.svg` above corresponds to the shortcode `:material-information:` shown in the search.
 
+## How do I add a new "Applications" page?
+
+To include a new software page on the "Applications" index pages
+(`apps/index.md`, `apps/by_system.md`, `apps/by_license.md`, `apps/by_discipline`),
+you must add a YAML front matter at the beginning of the file (before the page title)
+with appropriate metadata. The frontmatter should look like this:
+
+```yaml
+---
+tags:
+  - <license type>
+catalog:
+  name: <software name>
+  description: <short description>
+  license_type: <license type>
+  disciplines:
+    - <discipline a>
+    - <discipline b>
+    - ...
+  available_on:
+    - web_interfaces:
+        - <system 1>
+        - <system 2>
+        - ...
+    - <system 1>
+    - <system 2>
+    - <system 3>
+    - ...
+---
+```
+
+For example, the front matter of MATLAB is:
+
+```yaml
+---
+tags:
+  - Academic
+catalog:
+  name: MATLAB
+  description: High-level technical computing language
+  license_type: Academic
+  disciplines:
+    - Mathematics and Statistics
+  available_on:
+    - web_interfaces:
+        - LUMI
+        - Puhti
+    - LUMI
+    - Puhti
+---
+```
+
+> [!IMPORTANT]
+> **Do not** edit the index pages by hand, as they are populated automatically by a script using the front matter data when the website is built.
+
+See also:
+
+* [How do I add a license tag to an application page?](#how-do-i-add-a-license-tag-to-an-application-page)
+* [How do I tag an application as available under a web interface?](#how-do-i-tag-an-application-as-available-under-a-web-interface)
+
 ## How do I add a license tag to an application page?
 
 The license tag is added inside the YAML front matter. Temporarily, the license type should be placed as a