Update and reorganize

docs/_dangling-content.md → docs/_content-backup/_dangling-content.md

@@ -40,6 +40,6 @@ Please refrain from:
 
 :::tip
 
-If you aren't contributing to an existing Spec-Up-T project and want to create one yourself, you will have to install Spec-Up-T to start using it. Go straight to the [installation section](../getting-started/installation.md) for instructions. If you are contributing to an existing Spec-Up-T project you can contribute to content directly within GitHub's web editor (for example) by editing and adding the appropriate markdown files.
+If you aren't contributing to an existing Spec-Up-T project and want to create one yourself, you will have to install Spec-Up-T to start using it. Go straight to the [installation section](../../getting-started/installation.md) for instructions. If you are contributing to an existing Spec-Up-T project you can contribute to content directly within GitHub's web editor (for example) by editing and adding the appropriate markdown files.
 
 :::

docs/advanced-features/migration-2.md → docs/_content-backup/add.1.md

@@ -2,7 +2,7 @@
 sidebar_position: 60
 ---
 
-# Migrate content 2
+# Add content OLD
 
 **Pre condition: You have a Spec-Up installation up and running**
 
@@ -107,7 +107,7 @@ spec/terms-definitions/normative.md
 ```
 #### 2. Splitter-tool
 
-See [splitter tool documentation](./tools#splitter-tool)
+See [splitter tool documentation](../advanced-features/splitter#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. 
 
@@ -120,7 +120,7 @@ Spec-Up-T will:
 
 
 ### Feel free to reorganize the order of term in the glossary
-See [Migration reorganize glossary](./migration#feel-free-to-reorganize-the-order-of-term-in-the-glossary)
+See [Migration reorganize glossary](../advanced-features/migration#feel-free-to-reorganize-the-order-of-term-in-the-glossary)
 
 
 #### Npm run

docs/_content-backup/migration.1.md

@@ -0,0 +1,199 @@
+---
+sidebar_position: 100
+---
+
+# Migrate content OLD
+
+**Pre condition: You have a Spec-Up installation up and running**
+
+## When do you need this?
+
+You will need the instructions below if you have a **Spec-Up** installation and want to convert it to **Spec-Up-T**.
+
+## Why would you want this?
+
+Spec-Up-T has more features than Spec-Up.
+
+## What you'll need
+
+- A terminal / Command Line
+- An editor, also called IDE (Integrated Development Environment). We recommend Visual Studio Code, but an editor in which you can quickly write Markdown is also good
+- [Node.js](https://nodejs.org/en/download/):
+  - When installing Node.js, you are recommended to check all checkboxes related to dependencies
+  - Use Node.js version 18 or higher
+  - If you are running a Spec-Up installation you already have Node.js installed
+- 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
+
+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.
+- Node.js: This makes Spec-Up and Spec-Up-T run
+- Git: A system to track and manage changes in your code.
+
+:::
+
+## Save your data
+
+Back-up Specs.json to specs-backup.json
+
+Back-up package.json to 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-boilerplate/specs.json) from the starter pack and save into the root of the repo.
+
+## Modify your Spec-Up installation with Spec-Up-T install
+
+We consider migration a task for the roles `developer` or `administrator`.
+
+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. Spec-Up-T will:
+
+- create the `terms-index.json` in the root of the repo
+- generate the glossary in `index.html`
+- creates `specs-generated.json` in the output directory, DON'T TOUCH
+
+By hand you have to:
+
+```
+cd ./spec
+pwd
+touch terms-and-definitions-intro.md
+```
+
+This creates `terms-and-definitions-intro.md` in the `/spec` directory DON'T TOUCH this file further
+
+### Feel free to reorganize the order of term in the glossary
+Open the `terms-index.json` with a text editor in the root of the repo and change the order of terms. You can even throw terms out.
+
+:::note Plan to change
+`terms-index.json` will be a file that can't be editted by the user. We'll create the following process:
+- a user bypasses a term file (that is in draft) using an `_` (underscore) as the first character of the file name
+- a user create a custom order (default: alphabetically) by putting an order number as the first 3 characters of a filename. Example: `10_validator.md`, `15_autonomous-identifier.md`, etc.
+
+This method is adopted from Docusaurus.
+:::  
+
+### Prepare specs.json
+
+
+#### We copy the new specs.json structure for Spec-Up-T
+
+```
+{
+    "specs": [
+        {
+            "title": "Spec-Up-T Starterpack",
+            "spec_directory": "./spec",
+            "spec_terms_directory": "terms-definitions", | <- choose your name! |
+            "output_path": "./docs",
+            "markdown_paths": [
+                "intro.md",
+            **| copy your .md files here, listed in specs.json-backup, excluding the terminology md files |**
+            ],
+            "logo": "https://raw.githubusercontent.com/blockchainbird/spec-up-t-starter-pack/main/spec-up-t-boilerplate/logo.svg",
+            "logo_link": "https://github.com/blockchainbird/spec-up-t",
+            "source": {
+                "host": "github",
+                "account": "blockchainbird",
+                "repo": "spec-up-t-demo-on-documentation-website"
+            },
+            "external_specs": [
+                {
+                    "test-1": "https://blockchainbird.github.io/spec-up-xref-test-1/"
+                },
+                {
+                    "test-2": "https://blockchainbird.github.io/spec-up-xref-test-2/"
+                }
+            ],
+            "external_specs_repos": [
+                {
+                    "external_spec": "test-1",
+                    "url": "https://github.com/blockchainbird/spec-up-xref-test-1",
+                    "terms_dir": "spec/term-definitions"
+                },
+                {
+                    "external_spec": "test-2",
+                    "url": "https://github.com/blockchainbird/spec-up-xref-test-2",
+                    "terms_dir": "spec/term-definitions"
+                }
+            ],
+            "katex": false,
+            "searchHighlightStyle": "ssi"
+        }
+    ]
+}
+```
+
+**Be sure to get the latest specs.json [here](https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-boilerplate/specs.json)**
+
+Copy your old order of files from `specs-backup.json` and add `terms-and-definitions-intro.md` somewhere in the list (you choose the order!)
+
+#### Alter package.json
+Follow the instructions here: [Update package.json](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#packagejson)
+
+#### Copy Spec-Up-T specific files
+Follow the instructions here: [Make Spec-Up-T operational](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#copy-files-to-the-root-of-your-installation)
+
+#### Terms in their own directory
+| TBW why are we doing this | 
+You should place the terms in their own directory. This directory is defined in specs.json as `spec_terms_directory`.
+
+Alter the configuration according to your wishes and place all term-files the directory. Also see [Organize your Terminology data](#organize-your-terminology-data)
+
+#### Npm Install
+Delete your `node_modules` directory and `package-lock.json` file.
+
+Install Spec-Up-T and install all dependencies:
+```
+npm install
+```
+:::note Ignore warnings
+During the process, you can ignore the NPM warnings. 
+
+Keeping up-to-date with warnings would demand a daily effort from programmers and maintainers. Things change so quickly but are hardly ever a breaking change.
+:::
+
+:::todo Optional extra check
+Do the extra check with the "NPM list" command to see whether your install or update command has worked as expected. Check the packages and their latest version numbers. 
+:::
+
+Go into the menu
+
+```
+npm run menu
+```
+
+Add new terms: option 6
+
+Generate the specification
+
+```
+npm run menu
+1
+```
+
+It can take some time, and you should see multiple lines of output during installation.
+
+When the prompt is visible again, you should now have a Spec-Up-T install of your former Spec-Up install:
+
+- a `specs.json` file of the Spec-Up-T structure
+- a `spec/` directory with your markdown files
+- a `node_modules` directory, and a `package-lock.json` file (these elements belong to the `npm` system together with the earlier processed, modified-by-hand `package.json`)
+
+What you also should have is:
+
+- a `docs` directory with a generated `index.html` file (which is the actual specification file that is the goal of it all).
+
+### Add repo to Github
+
+Follow the steps to take here if you want to use a different account or repo: [Add repo to Github](https://trustoverip.github.io/spec-up-t-website/docs/various-roles/admins-guide/updating/#copy-files-to-the-root-of-your-installation)
+
+## Organize your Terminology data
+- Split your Terms and Definition into separate files under a directory in `/spec` directory

docs/advanced-features/tools.md → docs/_content-backup/splitter.1.md

@@ -2,9 +2,8 @@
 sidebar_position: 3
 ---
 
-# Extra Tools
+# Splitter Tool OLD
 
-## Splitter Tool
 
 ### Introduction
 

docs/advanced-features/add-content.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 60
+---
+
+# Add Content
+
+:::warning
+
+Work in process
+
+:::
+
+## Overview:
+This process outlines the steps to add content to a new Spec-Up-T installation by migrating data from an existing Spec-Up repository and organizing terms for efficient management.
+
+## Steps:
+
+1. **Prepare for Migration:**
+   - Ensure you have a working Spec-Up installation.
+   - Rename your existing GitHub repository and `.github.io` site (e.g., `Main-KERI-glossary` to `Main-KERI-glossary-OLD`).
+   - Rename your local directory accordingly (e.g., `Main-KERI-glossary-OLD`).
+
+2. **Set Up the New Repository:**
+   - Create a new empty directory with the established name (e.g., `Main-KERI-glossary`).
+   - Initialize the directory as a Git repository:
+     ```bash
+     cd <new_directory_name>
+     git init
+     ```
+   - Link it to the new GitHub repository:
+     ```bash
+     git remote set-url origin <URL_to_new_GitHub_repo>
+     ```
+
+3. **Install Spec-Up-T:**
+   - Follow the installation steps for Spec-Up-T:
+     ```bash
+     npx create-spec-up-t <directory_name>
+     ```
+
+4. **Migrate Data:**
+   - Copy the `markdown_paths` from `specs.json` in the old repository to the new one, excluding `terms-definitions.md`.
+   - Move markdown files from the old repository to the `/spec` directory of the new one.
+
+5. **Organize Terms:**
+   - Split `terms-definitions.md` into individual files, naming each file after its corresponding term. Place these files in a dedicated `terms-definitions` directory.
+     - For automation, use the Splitter Tool (see **Tools** section).
+
+6. **Generate Specification:**
+   - Use the Spec-Up-T menu to add terms and generate the specification:
+     ```bash
+     npm run menu
+     ```
+
+7. **Finalize:**
+   - Push the new repository to GitHub.
+   - Archive the old repository for reference.
+
+---
+
+