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)

police car light 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???

  • No labels