Modify version description hint and use Pandoc 3.8.3 in doc workflow

[JeremyYao]

Context

During release of daffodil-vscode 1.5.0, we observed that the site for 1.5.0 (https://daffodil.apache.org/vscode/1.5.0/) doesn't have links to docs.

We observed that the workflow for creating documentation needed to be run manually as shown in https://github.com/apache/daffodil-site/actions/workflows/update-docs.yml.

I initiated a manual run to create docs for daffodil-vscode 1.5.0 https://github.com/apache/daffodil-site/actions/runs/21040291571 which failed as the flag --embed-resources isn't supported in pandoc versions below 3.x.x

Description of Fixes

Updates the workflow dependencies install to utilize pandoc 3.8.3 (latest) which supports --embed-resources.

Change the formatting hint for specifying version syntax for both daffodil and daffodil-vscode respectively

Validation performed

Workflows were tested on my fork's main branch for both daffodil-vscode and daffodil.

Commits

• JeremyYao@17dd5b0
• JeremyYao@8967c6d

Workflow runs

• https://github.com/JeremyYao/daffodil-site/actions/runs/21041785786
• https://github.com/JeremyYao/daffodil-site/actions/runs/21041357549

[stevedlawrence]

+1, minor suggetions

[stevedlawrence]

Would it work to download the .deb (same link just with .deb instead of .tar.gz) and install that? Might be just a bit simpler than having to extract a tar and move files.

[JeremyYao]

Yup it would work with the .deb file and would be simpler indeed.

Made the changes and did a quick validation workflow run. It seems to work w/ the change

https://github.com/JeremyYao/daffodil-site/actions/runs/21043333693/workflow

[stevedlawrence]

You should be able use the same vX.Y.Z-rcx for both daffodil and vscode.

The "Extract Version" step expects the version input to include the v and rcX and strips them off.

I think this would be preferred for consistency, and also if vscode ever moves docs into the main repo (I think there was some discussion to do this?), then we can change the checkout action to just be

  ref: $inputs.project

so that it checks out the tag instead of the wiki master branch.

[JeremyYao]

I didn't notice the Extract Version step which normalizes the version number. I'll remove changes to this line. Thank you!

[JeremyYao]

One more thing, I did notice that the original Extract Version doesn't seem to work for a string like this v1.5.0, as it doesn't contain a -which -.*$ doesn't catch. I'll be including updates to extract version (see https://github.com/JeremyYao/daffodil-site/actions/runs/21042968791)

[stevedlawrence]

Documentation is intended to be built for release candidates and reviewed as part of the release process (I guess we forgot to do that, should be added to release checklists). Updating documentation after a release is generally discouraged. Since the documentation wasn't built for 1.5.0 due to error, I would suggest just running the action with v1.5.0-rc1 and it should do the right thing.