spec-up-t 0.11.29 → 0.11.31

package/readme.md

@@ -7,165 +7,6 @@
 <h2 style="display: block; margin: 0 auto; text-align: center;">Markdown » Spec-Up</h2>
 </div>
 
-## Intro
+There is a [special website that documents everything regarding Spec-Up-T](https://blockchainbird.github.io/spec-up-t-website/).
 
-Spec-Up is a technical specification development tool that enables you to create rich specification documents for standards bodies and engineering projects by writing in an extended version of markdown that features all the bells and whistles - for example: advanced syntax highlighting, notice blocks, complex tables, charts, UML diagrams, and more.
-
-Spec-Up-T is an expansion of [DIF's Spec-Up](https://github.com/decentralized-identity/spec-up) specifically for the needs of the Trust-over-IP foundation. Read more in the elaborate motivation in this technical article [Spec-Up-T, the ToIP Terms extension of Spec-Up](https://hackmd.io/s1TEBBluQBSL10ZT5yRVPw)
-
-## Extension
-
-Spec-Up-T stays in sync with Spec-Up, and currently adds the following extra functionality:
-1. Search & Find
-2. Splitter for Terms and Definition section following the [Termininology Governance Guide](https://trustoverip.github.io/ctwg-terminology-governance-guide/) and various meeting report since [CTWG April 2024](https://wiki.trustoverip.org/display/HOME/2024-04-22+CTWG+Meeting+Notes).
-
-## Setup
-
-Install Spec-Up-T as follows:
-
-- Open your terminal and go to the target directory
-- Run `npx create-spec-up-starterpack@latest`
-This will create a working Spec-Up-T installation in a new directory called `spec-up-t-starter-pack`
-
-- Rename this directory to your liking, for example `my-new-specification`
-- Go into this dir:
-`cd my-new-specification`
-You are now in this dir.
-
-- Install all dependencies:
-`npm run install`
-
-Now you have a basic Spec-Up-T install with the following content:
-- a `specs.json` file
-- a `spec/` directory with a sample markdown files
-- (and more)
-
-The`specs.json` file **in the root folder of your repository** specifies configuration values used in the generation of your spec documents. The values in your `specs.json` file include things like where your spec's markdown files are located, where to output the generated spec document, and various metadata values used in rendering, such as the title, logo, and repo links for each of your specs. The following are the required/optional fields supported in the `specs.json` config file:
-
-    - **`public_root`** _(PATH STRING, optional)_ - For some platforms and services where you may want to output your rendered spec, the pathing may differ from the directory structure of your local project. To account for this, you can use the `public_root` property to specify the insertion of a path segment to account for the different in pathing between your local renders and wherever you publish your spec to.
-    - **`specs`** _(ARRAY, required)_ - the `specs` array contains descriptor objects for each of the specs you are generating in your project, and are composed of the following required and optional properties:
-        - **`spec_directory`** _(STRING, required)_ - You must specify the **repo-root-relative** location of your spec's markdown file directory. You ****MUST**** name your spec's markdown file `spec.md` and locate it in your `spec_directory` for the tool to automatically find and use it for rendering. If you want to use a different name for the markdown file, or you have multiple markdown files you would like the tool to assemble into one document, you must specify them using the optional`markdown_paths` field described below. See the "multi-file" example in the spec-up repo.
-        - **`title`** _(STRING, required)_ - You must add a title for your spec, which will be rendered in the generated document's H1 text and page title.
-        - **`logo`** _(PATH/URI STRING, optional)_ - You may add a reference to a logo asset, either via a path to the asset or a URI
-        - **`logo_link`** _(URI STRING, optional)_ - The URI you want your logo to point to in the rendered page.
-        - **`markdown_paths`** _(ARRAY, optional)_ - If you want to name your spec's markdown file something other than `spec.md`, or you have multiple files you would like assembled into a single output document, you must specify their paths as array entries in the order you would like them assembled. The paths in this array are assumed to be based on the `spec_directory` you specified, so _DO NOT_ repeat the full root relative path.
-        - **`katex`** _(BOOLEAN, optional)_ - To enable TeX support via KaTeX, set this property to `true`. After rendering, be sure to copy the `fonts/` subdirectory, containing the necessary web fonts.
-        - **`output_path`** _(STRING, optional)_ - If you want the generated spec document to be output to a different location than the `spec_directory` you specified (e.g. the project root for GitHub Pages publishing) you can specify another root relative path (use `./` for root), and the tool will write the document file there instead.
-        - **`source`** _(OBJECT, optional)_ - this object allows you to configure where repo-specific data is pulled from to power some of the more advanced repo-related features. To do this, specify the code hosting service by adding a service ID string to `host` (currently Spec-Up only supports `"github"`, but this is extensible), add the account/org the repo is located within via the `account` property, and add the repo name under the `repo` property. Here is an example configuration:
-
-            ```
-            {
-                "host": "github",
-                "account": "decentralized-identity",
-                "repo": "sidetree"
-            }
-            ```
-
-You're ready to start rendering specs as HTML sites locally and/or pushing them to github pages however you see fit to automate.
-
-## Running the scripts locally
-
-If your `spec.json` and `package.json` and `package-lock.json` files are in working order and in the root folder of the repo from which it will be deployed, Spec-up can be called by command line (from the root of your repo) in three different modes:
-
-|command|behavior|
-|---|---|
-|`npm run edit`|after rendering, this will stay running and the `gulp` library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.|
-|`npm run render`|this renders the site once and does not keep a gulpy watch on the underlying files.|
-|`npm run dev`|this enables debugging features.|
-
-## Automation
-
-The above scripts can easily be triggered by github actions.  See [this repo's example](https://github.com/decentralized-identity/spec-up/blob/master/.github/workflows/render-specs.yml)
-
-## Versioning
-
-The recommended method for hosting multiple historical versions of a given specification at the same URL is simply to duplicate the source file(s) in a subdirectory and to host each version in a fixed subdirectory of the output target (i.e., the GitHub-Pages site). These multiple set-up and output directories can be set by multiple `spec` objects in the `specs` array of the `spec.json` file. For example:
-
-```json
-{
-  "specs": [
-    {
-      "title": "Wallet And Credential Interactions",
-      "spec_directory": "./",
-      "output_path": "./build",
-      "logo": "https://rawcdn.githack.com/decentralized-identity/decentralized-identity.github.io/a3ca39717e440302d1fd99a796e7f00e1c42eb2d/images/logo-flat.svg",
-      "logo_link": "https://identity.foundation",
-      "source": {
-        "host": "github",
-        "account": "decentralized-identity",
-        "repo": "waci-presentation-exchange"
-      }
-    },
-    {
-      "title": "Wallet And Credential Interactions",
-      "spec_directory": "./v0.1.0",
-      "output_path": "./build/v0.1.0",
-      "logo": "https://rawcdn.githack.com/decentralized-identity/decentralized-identity.github.io/a3ca39717e440302d1fd99a796e7f00e1c42eb2d/images/logo-flat.svg",
-      "logo_link": "https://identity.foundation",
-      "source": {
-        "host": "github",
-        "account": "decentralized-identity",
-        "repo": "waci-presentation-exchange"
-      }
-    }   
-  ]
-}
-```
-*Note: when copying a version into a subdirectory, relative references, including image links or [[include]] blocks that copy in example files or test vectors, may break; a quick CTRL-F "../" is recommended*
-
-In the above example, the files in `./v0.1.0` will not be rendered by the build process that searches "./" for markdown files and vice versa-- changing either will not trigger a new build of the other in each PR.
-
-### Version numbering
-
-DIF Recommends 3-decimal versions à la SemVer (i.e., v0.1.0 instead of v0.1).
-
-### Cross-linking across versions
-
-Links from the currently/nightly/unstable spec to stable/archival versions and vice versa are not automatically generated by the current version of spec-up, so the recommended best practice is to manually add links above the "Editors" section.  See:
-
-<details><summary>Examples from Presentation Exchange</summary>
-
-Unstable version:
-```
-Presentation Exchange 2.0.0
-==================
-
-**Specification Status:** Working Group Draft
-
-**Latest Draft:**
-  [identity.foundation/presentation-exchange](https://identity.foundation/presentation-exchange)
-
-**Ratified Versions:**
-~ **v1.0.0** - [https://identity.foundation/presentation-exchange/spec/v1.0.0](https://identity.foundation/presentation-exchange/spec/v1.0.0)
-
-```
-
-Stable Version:
-```
-Presentation Exchange v1.0.0
-==================
-
-**Specification Status:** DIF Ratified Specification
-
-**Latest Draft:**
-  [identity.foundation/presentation-exchange](https://identity.foundation/presentation-exchange)
-```
-</details>
-
-### Archiving stable versions beyond github
-
-Additionally, some editors may prefer to keep an immutable archive in a system like web.archive.org.  For example:
-
-```
-**Specification Status:** Draft V0.1 (snapshotted and archived on [web.archive.org](https://web.archive.org/web/20211206215823/https://identity.foundation/waci-presentation-exchange/))
-```
-
-## Troubleshooting
-
-- WSL2 users are recommended to use the `bash` option rather than `PowerShell` in the terminal of Visual Studio Code.
-- Some users have reported problems using spec-up with node versions 15+; to pin to an older version, simple run:
-```
-nvm install 14
-nvm use 14
-npm i npm@6.14.16 -g
-```
+Important: the files in `/spec` are identical to those in https://github.com/blockchainbird/spec-up-t-starter-pack/tree/main/spec-up-t-starterpack/spec. If one of the copies is modified, it must be copied over to the other copy. Also make sure the `"markdown_paths"` in `specs.json` are still correct.

package/spec/example-markup-in-markdown.md

@@ -0,0 +1,384 @@
+## Demo of example markup in Spec-Up-T and Markdown
+
+### Blockquote
+
+> To be, or not to be, that is the question:
+Whether 'tis nobler in the mind to suffer
+The slings and arrows of outrageous fortune,
+Or to take arms against a sea of troubles
+And by opposing end them. To die—to sleep,
+No more;
+
+### Notices
+
+<pre>
+::: note Basic Note
+  Check this out.
+:::
+</pre>
+
+::: note Basic Note
+  Check this out.
+:::
+
+::: note
+  Here's another.
+:::
+
+::: note
+  And one more!
+:::
+
+::: note Basic Note
+  One last note!!!
+:::
+
+<pre>
+::: issue Issue Notice
+  I take issue with that, kind sir.
+:::
+</pre>
+
+::: issue Issue Notice
+  I take issue with that, kind sir.
+:::
+
+<pre>
+::: warning Warning Notice
+  Houston, I think we have a problem
+:::
+</pre>
+
+::: warning Warning Notice
+  Houston, I think we have a problem
+:::
+
+<pre>
+::: todo Really Important
+  Get this done!
+:::
+</pre>
+
+::: todo Really Important
+  Get this done!
+:::
+
+<pre>
+::: example Code Example
+  Put your code block here
+:::
+</pre>
+
+::: example Code Example
+
+```json
+// Some comment in JSON
+{
+  "foo": "bar",
+  "baz": 2
+}
+```
+
+:::
+
+### Content Insertion
+
+Use the following format to pull in content from other files in your project:
+
+<pre>
+This text has been inserted here from another file: &#91;&#91;insert: assets/test.text&#93;&#93;
+</pre>
+
+This text has been inserted here from another file: [[insert: assets/test.text]]
+
+You can even insert content within more complex blocks, like the JSON object below which is being pulled in and rendered in a syntax-highlighted example block:
+<pre>
+::: example Code Example
+```json
+&#91;&#91;insert: assets/test.json&#93;&#93;
+```
+:::
+</pre>
+
+::: example Code Example
+
+```json
+[[insert: assets/test.json]]
+```
+
+:::
+
+### Tables
+
+<pre>
+Stage | Direct Products | ATP Yields
+----: | --------------: | ---------:
+Glycolysis | 2 ATP ||
+^^ | 2 NADH | 3--5 ATP |
+Pyruvaye oxidation | 2 NADH | 5 ATP |
+Citric acid cycle | 2 ATP ||
+^^ | 6 NADH | 15 ATP |
+^^ | 2 FADH2 | 3 ATP |
+**30--32** ATP |||
+[Net ATP yields per hexose]
+</pre>
+
+Stage | Direct Products | ATP Yields
+----: | --------------: | ---------:
+Glycolysis | 2 ATP ||
+^^ | 2 NADH | 3--5 ATP |
+Pyruvaye oxidation | 2 NADH | 5 ATP |
+Citric acid cycle | 2 ATP ||
+^^ | 6 NADH | 15 ATP |
+^^ | 2 FADH2 | 3 ATP |
+**30--32** ATP |||
+[Net ATP yields per hexose]
+
+<pre>
+|--|--|--|--|--|--|--|--|
+|♜|  |♝|♛|♚|♝|♞|♜|
+|  |♟|♟|♟|  |♟|♟|♟|
+|♟|  |♞|  |  |  |  | |
+|  |♗|  |  |♟|  |  | |
+|  |  |  |  |♙|  |  | |
+|  |  |  |  |  |♘|  | |
+|♙|♙|♙|♙|  |♙|♙|♙|
+|♖|♘|♗|♕|♔|  |  |♖|
+</pre>
+
+|--|--|--|--|--|--|--|--|
+|♜|  |♝|♛|♚|♝|♞|♜ |
+|  |♟|♟|♟|  |♟|♟|♟ |
+|♟|  |♞|  |  |  |  |  |
+|  |♗|  |  |♟|  |  |  |
+|  |  |  |  |♙|  |  |  |
+|  |  |  |  |  |♘|  |  |
+|♙|♙|♙|♙|  |♙|♙|♙ |
+|♖|♘|♗|♕|♔|  |  |♖ |
+
+### Sequence Diagrams
+
+<pre>
+```mermaid
+sequenceDiagram
+  Alice ->> Bob: Hello Bob, how are you?
+  Bob-->>John: How about you John?
+  Bob--x Alice: I am good thanks!
+  Bob-x John: I am good thanks!
+  Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
+
+  Bob-->Alice: Checking with John...
+  Alice->John: Yes... John, how are you?
+```
+</pre>
+
+```mermaid
+sequenceDiagram
+  Alice ->> Bob: Hello Bob, how are you?
+  Bob-->>John: How about you John?
+  Bob--x Alice: I am good thanks!
+  Bob-x John: I am good thanks!
+  Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
+
+  Bob-->Alice: Checking with John...
+  Alice->John: Yes... John, how are you?
+```
+
+### Flows
+
+<pre>
+```mermaid
+graph TD
+  A[Start] --> B{Is it?}
+  B -->|Yes| C[OK]
+  C --> D[Rethink]
+  D --> B
+  B -->|No| E[End]
+```
+</pre>
+
+```mermaid
+graph TD
+  A[Start] --> B{Is it?}
+  B -->|Yes| C[OK]
+  C --> D[Rethink]
+  D --> B
+  B -->|No| E[End]
+```
+
+### Charts
+
+<pre>
+```chart
+{
+  "type": "pie",
+  "data": {
+    "labels": [
+      "Red",
+      "Blue",
+      "Yellow"
+    ],
+    "datasets": [
+      {
+        "data": [
+          300,
+          50,
+          100
+        ],
+        "backgroundColor": [
+          "#FF6384",
+          "#36A2EB",
+          "#FFCE56"
+        ],
+        "hoverBackgroundColor": [
+          "#FF6384",
+          "#36A2EB",
+          "#FFCE56"
+        ]
+      }
+    ]
+  }
+}
+```
+</pre>
+
+```chart
+{
+  "type": "pie",
+  "data": {
+    "labels": [
+      "Red",
+      "Blue",
+      "Yellow"
+    ],
+    "datasets": [
+      {
+        "data": [
+          300,
+          50,
+          100
+        ],
+        "backgroundColor": [
+          "#FF6384",
+          "#36A2EB",
+          "#FFCE56"
+        ],
+        "hoverBackgroundColor": [
+          "#FF6384",
+          "#36A2EB",
+          "#FFCE56"
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Syntax Highlighting
+
+<pre>
+```json
+{
+  "@context": "https://www.w3.org/ns/did/v1",
+  "id": "did:example:123456789abcdefghi",
+  "authentication": [{
+    "id": "did:example:123456789abcdefghi#keys-1",
+    "type": "RsaVerificationKey2018",
+    "controller": "did:example:123456789abcdefghi",
+    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
+  }],
+  "service": [{
+    "id":"did:example:123456789abcdefghi#vcs",
+    "type": "VerifiableCredentialService",
+    "serviceEndpoint": "https://example.com/vc/"
+  }]
+}
+```
+</pre>
+
+```json
+{
+  "@context": "https://www.w3.org/ns/did/v1",
+  "id": "did:example:123456789abcdefghi",
+  "authentication": [{ 
+    "id": "did:example:123456789abcdefghi#keys-1",
+    "type": "RsaVerificationKey2018",
+    "controller": "did:example:123456789abcdefghi",
+    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
+  }],
+  "service": [{
+    "id":"did:example:123456789abcdefghi#vcs",
+    "type": "VerifiableCredentialService",
+    "serviceEndpoint": "https://example.com/vc/"
+  }]
+}
+```
+
+### TeX Math Equations
+
+When the `katex` option is enabled, the KaTeX math engine is used for TeX rendering. You can find a list of supported features and examples here: <https://katex.org/docs/supported.html>.
+
+$$\begin{pmatrix}x_2 \\ y_2 \end{pmatrix} =
+\begin{pmatrix} A & B \\ C & D \end{pmatrix}\cdot
+\begin{pmatrix} x_1 \\ y_1 \end{pmatrix}$$
+
+$$\def\arraystretch{1.5}
+   \begin{array}{c:c:c}
+   a & b & c \\ \hline
+   d & e & f \\
+   \hdashline
+   g & h & i
+\end{array}$$
+
+$$
+\underbrace{a+b+c}_{\text{Note: such math, much wow.}}
+$$
+
+### Tab Panels
+
+<tab-panels selected-index="0">
+  <nav>
+    <button type="button">First Tab</button>
+    <button type="button">Second Tab</button>
+  </nav>
+
+  <section>
+
+```json
+{
+  "foo": "foo",
+  "baz": 1
+}
+```
+
+  </section>
+  <section>
+
+```json
+{
+  "foo": "bar",
+  "baz": 2
+}
+```
+
+  </section>
+</tab-panels>
+
+### Fancy Links
+
+Spec-Up automatically upgrades the links of certain sites, like GitHub. GitHub is the only supported site with Fancy Links right now, but we'll be adding more as we go.
+
+### GitHub
+
+- **Issues**
+  - Source: `https://github.com/decentralized-identity/presentation-exchange/issues/119`
+  - Render: https://github.com/decentralized-identity/presentation-exchange/issues/119
+- **Pull Requests**
+  - Source: `https://github.com/decentralized-identity/sidetree/pull/863`
+  - Render: https://github.com/decentralized-identity/sidetree/pull/863
+- **Releases**
+  - Source: `https://github.com/decentralized-identity/sidetree/releases/tag/v0.9.1`
+  - Render: https://github.com/decentralized-identity/sidetree/releases/tag/v0.9.1
+- **Projects**
+  - Source: `https://github.com/decentralized-identity/sidetree/projects/1`
+  - Render: https://github.com/decentralized-identity/sidetree/projects/1

package/spec/intro.md

@@ -0,0 +1,7 @@
+# Spec-Up-T Demo
+
+## Intro
+
+This is a default Spec-Up-T installation. Find information on the [documentation website](https://blockchainbird.github.io/spec-up-t-website/).
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

package/spec/outro.md

@@ -0,0 +1,3 @@
+## Outro
+
+Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

package/spec/terms-and-definitions-intro.md

@@ -0,0 +1,5 @@
+# Terms and Definitions Intro
+
+## Demo terms, definitions and external definitions
+
+A demo of terms and definitions, and references to external definitions.

package/specs.json

@@ -1,24 +1,22 @@
 {
     "specs": [
         {
-            "title": "Spec-Up ToIP example",
+            "title": "Spec-Up-T",
             "spec_directory": "./spec",
             "spec_terms_directory": "terms-definitions",
             "output_path": "./docs",
             "markdown_paths": [
-                "title.md",
-                "header.md",
-                "toc.md",
-                "introduction.md",
-                "referenced_glossaries.md",
-                "terms_and_definitions.md",
+                "intro.md",
+                "terms-and-definitions-intro.md",
                 "terms-definitions/term-1.md",
                 "terms-definitions/term-2.md",
                 "terms-definitions/term-3.md",
-                "terms-definitions/term-4.md"
+                "terms-definitions/term-4.md",
+                "example-markup-in-markdown.md",
+                "outro.md"
             ],
-            "logo": "../logo.svg",
-            "logo_link": "https://github.com/decentralized-identity/spec-up",
+            "logo": "https://raw.githubusercontent.com/blockchainbird/spec-up-t/master/logo.svg",
+            "logo_link": "https://github.com/blockchainbird/spec-up-t",
             "source": {
                 "host": "github",
                 "account": "blockchainbird",
@@ -29,10 +27,10 @@
                     "PE": "https://identity.foundation/presentation-exchange"
                 },
                 {
-                    "test-1": "https://kordwarshuis.github.io/spec-up-xref-test-1/"
+                    "test-1": "https://blockchainbird.github.io/spec-up-xref-test-1/"
                 },
                 {
-                    "test-2": "https://kordwarshuis.github.io/spec-up-xref-test-2/"
+                    "test-2": "https://blockchainbird.github.io/spec-up-xref-test-2/"
                 }
             ],
             "external_specs_repos": [
@@ -43,12 +41,12 @@
                 },
                 {
                     "external_spec": "test-1",
-                    "url": "https://github.com/kordwarshuis/spec-up-xref-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/kordwarshuis/spec-up-xref-test-2",
+                    "url": "https://github.com/blockchainbird/spec-up-xref-test-2",
                     "terms_dir": "spec/term-definitions"
                 }
             ],