Relocated inline images

[tdcox]

Signed-off-by: Terry Cox terry@bootstrap.je

Changes

Remove need to use scripting to make image paths compatible with Docsy for publication.

Fixes cdevents/cdevents.dev#27

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has the primer doc been updated if a design decision is involved
• Have the JSON schemas been updated if the specification changed
• Has spec version and event versions been updated according to the versioning policy
• Meets the CDEvents contributor standards

[afrittoli]

Thank you @tdcox - Could you update links to the primer too?
There is one in the README at least 🙏

[tdcox]

Could you update links to the primer too?

@afrittoli Done.

[afrittoli]

Thank you for the update.
Some links needs to be updated.

[afrittoli]

This link may work on the website, but not on github

[afrittoli]

ditto

[afrittoli]

ditto

[afrittoli]

ditto

[tdcox]

@afrittoli Yes, unfortunately we have reached that point where it is no longer possible to reconcile the differences between the native GitHub environment and the Docsy environment. In all such cases, the links should be formatted to work on the system of record, which is cdevents.dev, in Docsy format.

Since the only people working directly on the spec repo will be contributors and maintainers, they will already be familiar with the location of these documents within the local repo.

[afrittoli]

@afrittoli Yes, unfortunately we have reached that point where it is no longer possible to reconcile the differences between the native GitHub environment and the Docsy environment.

I didn't realise we would run into this issue when you presented the different options to solve the issue with the path to the images. I tried the option of having images in the same folder as the markdown files, but that doesn't really work for me. It might work if primer.md was called _index.md but that doesn't really fit with having multiple markdown files.

In all such cases, the links should be formatted to work on the system of record, which is cdevents.dev, in Docsy format.

If only publish one version to the website, a have the other version link to github, then we'll have broken links for everyone except those on the latest version. Today it's only an issue for primer.md but it may become an issue for other docs if we wanted to include more pictures, unless we decided that we cannot use pictures in the spec files.

I see the following options:

• use an absolute link in versions published to cdevents.dev, use a github format relative link for versions only available via GitHub
• replace the git submodule with a sync script (that's what we do for Tekton) that will overwrite links
• maintain a -docsy version of each branch we publish to cdevents.dev. Use automation to update that branch whenever the corresponding branch is updated. Update the website to pick content from the -docsy branch(es)
• decide we'll only ever host images in primer.md and possibly relocated that document to the website.

[tdcox]

@afrittoli We are about to see multiple similar issues as we add additional documentation to the site, independent from the requirement for images. I think that the real question is whether it is appropriate to try to maintain documentation outside the website repo, and require it to be functionally independent from the website itself?

I would suggest that the risk is that a lot of brittle work-arounds and scripts are likely to start accumulating, resulting in a high maintenance overhead, for what should be a trivial application.

It might be much easier to just move all of the spec documents into cdevents.dev, and use the spec repo for the schemas and code. Versioning can be managed with working branches.

We need a decision quickly, however, as we are running out of time to complete the remaining work in this refresh and this is a blocker.

[afrittoli]

It might be much easier to just move all of the spec documents into cdevents.dev, and use the spec repo for the schemas and code. Versioning can be managed with working branches.

I don't think this would solve the issue with links to images.

[afrittoli]

We need a decision quickly, however, as we are running out of time to complete the remaining work in this refresh and this is a blocker.

I don't think this is a blocker for any other work, but I'm ok to merge this in the interest of avoiding rebase of other PRs.
We can address broken links later.

[afrittoli]

Having the primer in a dedicated folder sounds like a good idea.