[jakarta.ee-spec] Changing specification _index.md pages

[Scott Stark <starksm64@xxxxxxxxx>]

So I did a quick look at how things like generation of the tck download urls might be done. There is a simple approach using hugo inline shortcodes, but this requires a configuration setting to be enabled. Since this is a minor security risk under some circumstances, I created an issue in the jakarta.ee repo to ask if that is a direction that could be explored:

https://github.com/jakartaee/jakarta.ee/issues/862

There is a link to a specification page PR that shows how that might work, but it currently does not render correctly because inline shortcodes are not enabled.

If that is not something we decide to allow, the alternative would be to change to a specification page template that is mostly or even purely driven by metadata. This would mean the specification PRs would just fill out a yaml or json file that lists the specification release information and then it would be rendered similar to the content we have today with any parameterized links generated from the metadata. Still have not looked into what that might look like as the simpler change is to use the inline shortcodes.

Below are just some notes I put together during a review of the docs and the current jakarta.ee site with respect to the specifications. I'll put it in a wiki at a later time once a direction is taken.

--- 

jakarta.ee site notes on the use of Hugo

- git repo for the site is https://github.com/jakartaee/jakarta.ee

- Hugo documentation: https://gohugo.io/content-management/front-matter#readout

Front Matter (https://gohugo.io/content-management/front-matter)

Your _index.md pages contain a section Hugo calls front matter that sets a number of Hugo variables. Our specifications use the YAML format where the front matter is contained in the

section delimited with `—`, e.g.:

Example from bean-validation/3.0/_index.md

---

title: "Jakarta Bean Validation 3.0"

date: 2020-07-07

summary: "Release for Jakarta EE 9"

---

The Front Matter documentation lists the known “predefined variables” that Hugo will recognize from the front matter section. The Page Variables documentation talks about how the front matter variables map to the page variables which are used by templates. Any variable `x` defined in the front matter sections that is not in the known Front Mater/Page Variables defined lists is a user specific variable that shows up in the page as .Page.PageParams.x. The front matter variables are inherited from parent _index.md files. For example, the bean-validation/3.0/_index.md from above has a parent of:

Front Matter for bean-validation/_index.md

---

title: "Jakarta Bean Validation"

summary: "Jakarta Bean Validation …”

project_id: "ee4j.bean-validation"

---

Both the summary and project_id variables are custom 

Specifications Layout

The current layout template is located at layouts/specifications/list.html

Inline Shortcodes

https://gohugo.io/templates/shortcode-templates/#inline-shortcodes