General Training

Here's a quick video about SpecUp that should help getting started.

Tips/Tricks/How-Tos

Do NOT Modify spec.json this way...

The spec.json file has a key reference that should ALWAYS remain set to the main repository.

Be sure that the "source" parameter is left as pointing at the main repository. As a CONSEQUENCE, this means that your forked repository will not likely render properly in your personal github.io space.

i.e. leave the account value as trustoverip not yours.

You can preview your changes (see below) with SpecUp.

"source": {
  "host": "github",
  "account": "trustoverip",
  "repo": "tswg-trust-registry-protocol"
},

Adding Images & Other Files

Put the images into the ./docs folder where your main content (or in a sub-folder like ./docs/images )

Reference these using regular image markdown:

![alternate text/title](./images/highlevel.png)

NOTE: if you don't use this approach your local preview may show images that DO NOT show when fully deployed in the main repository.

As an example, the Trust Registry Protocol publishes several inline items:

Rendered API browser using Redocs in the ./docs/api folder
Images from PlantUML diagrams in the ./docs/images/puml folder

These are created in the ./docs folder of the repository and are auto-published via SpecUp and can be linked.

See here for that example: https://github.com/trustoverip/tswg-trust-registry-protocol/tree/main/docs

Previewing/Rendering Locally

Run the following in your terminal (you will need to npm install before this will work):

One-time Render: npm run render
Constant Render: npm run edit

Linking GitHub Issues

When you configure the specs.json file, be sure to link the proper GitHub repository as the Issued list (top right corner) will come from that repo:

e.g for TRP

"source": {
  "host": "github",
  "account": "trustoverip",
  "repo": "tswg-trust-registry-protocol"
},

Calling Out a Single GitHub Issue

::: issue 
https://github.com/trustoverip/tswg-trust-registry-protocol/issues/5 
- Should align with Service Profiles/[Service Discovery] efforts
:::

will render out as (h/t: Eric Scouten )

Specification References - That Are Not Auto-Generated

SpecUp has a limited library of specification references that can be used "automagically" like [[spec-norm:RFC3119]] will render out automatically when the [[spec-norm]] tag is used.

The [[def:...]] and [[ref:...] capabilities can be used in the interim. Example:

# Some Section

EdDSA [[ref:Ed25519]]is a great!

# References

[[def:Ed25519]]
~ [Ed25519](https://ed25519.cr.yp.to/). D. J. Bernstein, N. Duif, T. Lange, P. Schwabe, B.-Y. Yang; 26 September 2011.
[ed25519.cr.yp.to](https://ed25519.cr.yp.to/).

[[spec-norm]]

OTHER???

Home

SpecUp Resources