Merge remote-tracking branch 'upstream/main'

.github/workflows/deploy-to-gh-pages.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main  # Set to your default branch
+  workflow_dispatch:
 
 jobs:
   deploy:

docs/general/add-content/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Add content",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "description": "Add content."
+  }
+}

docs/general/migration.md → docs/general/add-content/migration.md

@@ -1,8 +1,8 @@
 ---
-sidebar_position: 1
+sidebar_position: 100
 ---
 
-# Migration
+# Migrate content
 
 **Pre condition: You have a Spec-Up installation up and running**
 
@@ -16,7 +16,7 @@ sidebar_position: 1
 - A [webbrowser](https://en.wikipedia.org/wiki/Web_browser). You are probably reading this in a browser, so you already have one
 - [Git](https://git-scm.com/). To host your specification on Github, you must also have Git installed on your local system. By the way, you can also create a specification (index.html) without hosting it on GitHub. But if you do so, the whole idea of a version-managed glossary using Git goes through the window.
 
-::: note Non-technical Info
+:::note Non-technical Info
 Non-technical explanation:
 - Command Line: A text interface to type commands for your computer.
 - IDE: A software where you can easily write, test, and debug code.
@@ -31,8 +31,8 @@ Back-up Specs.json to specs-backup.json
 Back-up package.json to package-backup.json
 
 ```
-mv specs.json specs-backup.json
-mv package.json package-backup.json
+cp specs.json specs-backup.json
+cp package.json package-backup.json
 ```
 
 Be sure to get the latest specs.json [here](https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-starterpack/specs.json) from the starter pack and save into the root of the repo.

docs/general/populate.md → docs/general/add-content/populate.md

@@ -1,8 +1,8 @@
 ---
-sidebar_position: 1
+sidebar_position: 60
 ---
 
-# Populate a new install
+# New content
 
 **Pre condition: You have a Spec-Up installation up and running**
 
@@ -28,7 +28,7 @@ git init
 cd ..
 ```
 
-Now that you're outside the repo directory (!): Go over [Installation](./installation) and create a new repo with the established name. In the example `Main-KERI-glossary`, you start with: 
+Now that you're outside the repo directory (!): Go over [Installation](../installation) and create a new repo with the established name. In the example `Main-KERI-glossary`, you start with: 
 
 ```
 npx create-spec-up-t < established dirname >
@@ -107,8 +107,7 @@ spec/terms-definitions/normative.md
 ```
 #### 2. Splitter-tool
 
-See [splitter tool documentation](./various-roles/admins-guide/tools?_highlight=splitter#splitter-tool)
-
+See [splitter tool documentation](../../various-roles/admins-guide/tools#splitter-tool)
 
 It's about file management. It's in line with how static website generator generally work. So, be aware that you only organize your files in the migration process, you then configure your configuration files and you're good to go. 
 

docs/general/command-line-menu.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 26
 ---
 
 # Command Line Menu
@@ -27,38 +27,30 @@ You will now see this menu:
 ```bash
 Please choose one of the following options:
 
-    [0] Publish ¹
+   [0] Add content
+   [1] Render specification
+   [2] Export to PDF
+   [3] Update new xrefs
+   [4] Update all xrefs
+   [5] Add, remove or view xref source
+   [6] Configure
+   [7] Open documentation website
+   [8] Freeze specification
+   [Q] Quit
 
-    [1] Render specification
-    [2] Export to PDF
-    [3] Look up xrefs
-    [4] Remove xref
-    [5] Validate config file
-    [6] Add new terms
-    [7] Open documentation website
-    [8] Freeze specification
-    [Q] Quit
+   An xref is a reference to another repository.
 
-    ¹ Publish = [6]+[2]+[3]+[1]
-
-
-    Enter your choice (0/1/2/3/4/5/6/7/8/Q)?
+   Enter your choice:
 ```
 
 These menu options act as shortcuts to the below commands, such as `npm run render` and others. You can choose between using the menu or entering the direct commands yourself.
 
-### `[0] Publish`
-
-#### Info
-
-**Runs the below options in given order: [6]+[2]+[3]+[1].**
+### `[0] Add content`
 
-Use this if you use a GitHub token and, therefore, don't have to worry about the limited number of GitHub API calls you can make per hour.
+Gives info on how to add content.
 
 ### `[1] Render specification`
 
-#### Info
-
 **Creates the specification, an index.html, in the `docs` directory, as specified in the `specs.json` file.**
 
 To view the `index.html` file, you can:
@@ -68,7 +60,6 @@ To view the `index.html` file, you can:
 
 The easiest way is to double-click the file in your file manager, which should open it in your browser.
 
-
 By the way, there are **three** modes for rendering the specification:
 
 | Command | Behavior |
@@ -77,129 +68,44 @@ By the way, there are **three** modes for rendering the specification:
 | **`npm run render`** | Renders the site once without watching for changes. |
 | **`npm run dev`** | Enables debugging features. |
 
-#### Direct command
-
-```bash
-npm run render
-```
-
-- - -
-
-
 ### `[2] Export to PDF`
 
-#### Info
-
 **Creates a PDF. The PDF will be created in the same directory as the `index.html` file.**
 
-#### Direct command
-
-```bash
-npm run topdf
-```
-
-- - -
-
+### `[3] Update new xrefs`
 
-### `[3] Look up xrefs`
+**Creates all newly added “xref”'s (external references).**
 
-#### Info
-
-**Creates an “xref” (external reference).**
+Also runs [1].
 
 `xrefs` are references to external glossaries (specifications). Each `xref` is checked against a local data collection to see if a reference exists, maintaining an external term's original version.
 
-This separate command is not just used when generating a specification (option [1]) because, without a GitHub token, you are only allowed a limited number of calls to the GitHub API. So, you may choose not to create the xrefs until the end of your work session.
-
-#### Direct command
-
-```bash
-npm run xrefs
-```
-
-- - -
-
-### `[4] Remove xref`
-
-#### Info
-
-**Removes an “xref” (external reference).**
-
-After removing the old reference, you can run `npm run xrefs` again to get the latest reference.
+The xrefs are not always automatically looked up when you choose option [1] because every lookup invokes the GitHub API, and you are faced with a limit at some point. You then have to wait for the limitation to be lifted again. Without a unique token, you run into the limit pretty quickly. Hence this option to take it slow. By the way, you can create a token for free at GitHub.
 
-#### Direct command
+### `[4] Update all xrefs`
 
-```bash
-npm run removexref -- "termValue" "externalSpecValue"
-```
-
-- - -
-
-### `[5] Validate config file`
-
-#### Info
-
-**Tests the `spec.json` for missing keys.**
-
-Once you've edited the `spec.json`, you can test it to check for missing keys. If a key is missing, you'll receive a notification.
+**(re)creates all “xref” (external references).**
 
-#### Direct command
+If you delete an xref, it is also deleted from the system's bookkeeping.
 
-```bash
-npm run validatespec
-```
-- - -
-
-### `[6] Add new terms`
-
-#### Info
+### `[5] Add, remove or view xref source`
 
-Adds a new file (with a term) to the specification.
+**See an overview of all external references, or add or delete**
 
-If you create a new Markdown file with a term and definition in it, it is not automatically included in the final product. It can be included in the index only if you want it to be. With this command, you add it to the index.
-
-#### Direct command
-
-```bash
-npm run addterms
-```
+### `[6] Configure`
 
-- - -
+Configure a new installation.
 
 ### `[7] Open documentation website`
 
-#### Info
-
 This command will redirect to the documentation website (the site you are reading right now).
 
-#### Direct command
-
-No Direct command.
-
-- - -
-
 ### `[8] Freeze specification`
 
 **Makes a copy of the `index.html` file and adds a version number to the file name.**
 
 Example: `index-v1.html`, `index-v2.html` etc. These files are placed in the same folder as the `index.html` but in a subfolder called `versions`.
 
-#### Direct command
-
-```bash
-npm run freeze
-```
-
-- - -
-
 ### `[Q] Quit`
 
-#### Info
-
 This command will take you out of the menu.
-
-#### Direct command
-
-No Direct command.
-
-- - -

docs/general/configuration.md

@@ -1,37 +1,61 @@
 ---
-sidebar_position: 2
+sidebar_position: 25
 ---
 
 # Configuration
 
+The `specs.json` file, located in the root folder of your repository, specifies the configuration values used in generating your specification documents. Using the command line menu, you can configure the most important elements. The rest you can do manually.
+
 ## Create (or edit the sample) `spec.json`
 
-The `specs.json` file, located in the root folder of your repository, specifies the configuration values used in generating your specification documents. These values include the locations of your markdown files, the output path for the generated spec, and metadata like the title, logo, and repository links for each of your specs. Below are the required and optional fields supported in the `specs.json` config file:
+```json
+{
+    "specs": [
+        {
+            "title": "Spec-Up-T Starterpack",
+            "description": "Create technical specifications in markdown. Based on the original Spec-Up, extended with Terminology tooling",
+            "author": "Trust over IP Foundation",
+            "spec_directory": "./spec",
+            "spec_terms_directory": "terms-definitions",
+            "output_path": "./docs",
+            "markdown_paths": [
+                "spec-head.md",
+                "terms-and-definitions-intro.md",
+                "example-markup-in-markdown.md",
+                "spec-body.md"
+            ],
+            "logo": "https://raw.githubusercontent.com/trustoverip/spec-up-t-starter-pack/main/spec-up-t-starterpack/static/logo.svg",
+            "logo_link": "https://github.com/trustoverip/spec-up-t",
+            "favicon": "https://raw.githubusercontent.com/trustoverip/spec-up-t-starter-pack/main/spec-up-t-starterpack/static/favicon.ico",
+            "source": {
+                "host": "github",
+                "account": "trustoverip",
+                "repo": "spec-up-t-starter-pack"
+            },
+            "external_specs": [
+                {
+                    "external_spec": "test-1",
+                    "gh_page": "https://blockchainbird.github.io/spec-up-xref-test-1/",
+                    "url": "https://github.com/blockchainbird/spec-up-xref-test-1",
+                    "terms_dir": "spec/term-definitions"
+                },
+                {
+                    "external_spec": "test-2",
+                    "gh_page": "https://blockchainbird.github.io/spec-up-xref-test-2/",
+                    "url": "https://github.com/blockchainbird/spec-up-xref-test-2",
+                    "terms_dir": "spec/term-definitions"
+                }
+            ],
+            "katex": false
+        }
+    ]
+}
+```
 
-- **`public_root`** _(PATH STRING, optional)_: Used to specify a path segment for platforms where the directory structure may differ between local and published environments.
-- **`specs`** _(ARRAY, required)_: Contains descriptor objects for each spec in your project, including properties like:
-  - **`spec_directory`** _(STRING, required)_: The repo-root-relative location of your markdown file directory. The tool automatically searches for `spec.md` here unless otherwise specified in the optional `markdown_paths`.
-  - **`title`** _(STRING, required)_: The title for your spec, rendered in the document's H1 text and page title.
-  - **`logo`** _(PATH/URI STRING, optional)_: A reference to a logo asset via a path or URI.
-  - **`logo_link`** _(URI STRING, optional)_: The URI your logo points to on the rendered page.
-  - **`markdown_paths`** _(ARRAY, optional)_: Specifies alternative names for your markdown files or includes multiple files for assembly into a single document.
-  - **`katex`** _(BOOLEAN, optional)_: Enables TeX support via KaTeX when set to `true`.
-  - **`output_path`** _(STRING, optional)_: Specifies an alternative output location for the generated spec document.
-  - **`source`** _(OBJECT, optional)_: Configures the source of repo-specific data, such as the hosting service (`host`), account/org (`account`), and repository name (`repo`).
 
-You're now ready to start rendering specs as HTML sites locally and/or pushing them to GitHub Pages.
 
-## A complete installation
 
-This is what a complete installation looks:
 
-- a `specs.json` file
-- a `spec/` directory with sample markdown files
-- a `docs` directory with a sample index.html file
-- a `node_modules` directory, a `package.json` file, and a `package-lock.json` file (these three elements belong to the `npm` system)
 
-See [directory `spec-up-t-starterpack` of the installer](https://github.com/blockchainbird/spec-up-t-starter-pack/tree/main/spec-up-t-starterpack)
 
-## Automation
 
-The above scripts can easily be triggered by [GitHub Actions](../glossary#github-actions). See [this repo's example](https://github.com/decentralized-identity/spec-up/blob/master/.github/workflows/render-specs.yml).

docs/github-token.md → docs/general/github-token.md

@@ -1,12 +1,12 @@
 ---
-sidebar_position: 2
+sidebar_position: 90
 ---
 
 # GitHub Token
 
 ## Intro
 
-Because GitHub.com is where all specifications live, it is essential to have good access to it. This goes under the hood through the GitHub API (Application Programming Interface). You have access to this, but soon you run into a limit. To make more requests, you need a token. Here's how to get such a token and how to apply it.
+Because GitHub.com is where all specifications live, having good access to it is essential. This goes under the hood through the GitHub API (Application Programming Interface). You have access to this, but soon you run into a limit. To make more requests, you need a token. Here's how to get such a token and how to apply it.
 
 Steps to take: