search

tno-terminology-design / tev2-tools

The Terminology Engine (v2) is a set of specifications and tools that caters for the creation and maintenance (i.e. curation) of terminologies. This repository contains the sources for the tools.
Apache License 2.0
2 stars 3 forks source link

Differences between Docusaurus routing and TRRT link resolution #28

Closed RieksJ closed 9 months ago

RieksJ commented 9 months ago

When generating the TEv2 specs website, the build and deploy step produces a log of links that are not resolvable in the static website. Some of those messages are due to Docusaurus, but others are not. Here is an example

image

The log shows (line 38) a reference to terms/ingestion-process, which does not exist. However, in the source file, the only mention regarding ingestion is in line 16, that says ...and evolve to a level of maturity that warrants the text to be [ingested](@) into.... The showtext "ingested" is one of the specified form phrases mentioned in terms/ingestion-process.md, which also has the (docusaurus) id field saying ingestion.

Apparently, the link that the TRRT generates is based on the name of the file that contains the curated text, whereas docusaurus uses the id field in the curated text for routing.

This issue calls for suggestions to deal with this, e.g., in terms of what/how to document this, or what we can configure in the SAF/TRRT-config to ensure that the TRRT generates links that the static site correctly routes towards.

RieksJ commented 9 months ago

I renamed the file terms/ingestion-process.md into terms/ingestion.md which fixed this particular example of the issue.

Ca5e commented 9 months ago

I'm surprised we haven't found this sooner. Currently, the TRRT does not generate links, it only looks at the navurl value of an MRG entry (assuming this is used in the converter). The MRGT constructs the navurl based on the saf.scope.website, saf.scope.navpath, curated text directory, and curated text filename. When the id field is in the frontmatter of a curated text, the navurl indeed won't point to the URL as constructed by Docusaurus. We do handle the id field situation correctly in cases where we refer to a body file from a curated text, as this uses the bodyFileID that can be specified in the SAF to construct the final portion of the navurl. I suppose we could use the corresponding bodyFileID (which might then need a different name) in a curated text to create the navurl in every case, not just for body files.

RieksJ commented 9 months ago

How to create a navurl from a Curated Text:

  1. start with the curated text file, or with the bodyfile if there is one.
  2. if that file contains a field whose name is the value of saf.bodyFileID, then use the value of its field to construct navurl.
  3. otherwise, take the name of the file (ctext file or bodyfile).

SO: if someting goes wrong in the routing, then an author must ensure to use a saf.bodyFileID field with proper value.

Ca5e commented 9 months ago

How to create a navurl from a Curated Text:

  1. start with the curated text file, or with the bodyfile if there is one.
  2. if that file contains a field whose name is the value of saf.bodyFileID, then use the value of its field to construct navurl.
  3. otherwise, take the name of the file (ctext file or bodyfile).

SO: if someting goes wrong in the routing, then an author must ensure to use a saf.bodyFileID field with proper value.

Considering we’re using the bodyFileID SAF property now to construct all navurl’s in case it exists (not just those of body files), should this property not be renamed to ctextnameid or ctextnavid? Even navid may be an option as navpath also only applied to ctexts. This will also make all of the defined SAF properties lowercase again.

RieksJ commented 9 months ago

navid sounds fine.