Documentation📄: Update from Just-the-Docs to Docusaurus

[joewxboy]

What is the current documentation state?

Documentation is generated in Markdown, associated with each repository, moved to open-horizon.github.io repo when merged, and the site is generated in Jekyll with keywords abstracted out and inserted at page generation time.

Where is this stated?

No response

Why do you want to improve the statement?

The current solution is fragile and brittle, complex to learn and support, and does not support different versions per branch.

Proposed Statement

Migrating to Docusaurus 3.4 from Jekyll should address the above proposed improvements.

Additional context.

No response

[joewxboy]

Beginning to document migration choices at https://wiki.lfedge.org/display/OH/Migrate+GitHub+Pages+documentation+from+Jekyll+to+Docusaurus

[Abhijay007]

Hi @joewxboy,

I would like to assist with this issue. This is something I also suggested during my time with Open Horizon during the LFX program, but we dropped it due to an issue with the references (abstracted keywords maybe) in existing docs in the markdown. We can discuss more around it. Also, I recently migrated the Uptane documentation from Jekyll (https://uptane.org/) to Docusaurus, so I have some relevant experience with that, I will look into just-the-docs theme and see how we can proceed with the migration.

[joewxboy]

Hi @joewxboy,

I would like to assist with this issue.

Good to hear from you! I would appreciate that. :)

I'm struggling with trying to figure out how to implement two features in Docusaurus:

1. Variable substitution where we insert values at page generation time using {{site.data.keyword.ieam}} from the _data/keyword.yaml file.
2. Associating manually-generated IDs with HTML elements, like this:

# Accessing management hub logs
{: #accessing_logs}

[Abhijay007]

Hi @joewxboy, I would like to assist with this issue.

Good to hear from you! I would appreciate that. :)

I'm struggling with trying to figure out how to implement two features in Docusaurus:

1. Variable substitution where we insert values at page generation time using {{site.data.keyword.ieam}} from the _data/keyword.yaml file.

Ya this was something we faced previously, I will look into that, In the meantime I suggest you to drop this in the Docusaurus community on discord here , maybe they can help us to find a way around it.

[Abhijay007]

2. Associating manually-generated IDs with HTML elements, like this:

# Accessing management hub logs
{: #accessing_logs}

we did something similar in Uptane, you can follow these docs here : https://docusaurus.io/docs/3.3.2/markdown-features/toc#heading-ids , let me know if this is something we want to do with the IDs

[joewxboy]

we did something similar in Uptane, you can follow these docs here : https://docusaurus.io/docs/3.3.2/markdown-features/toc#heading-ids , let me know if this is something we want to do with the IDs

OK, so that appears to be as simple as converting this:

# Accessing management hub logs
{: #accessing_logs}

to this:

# Accessing management hub logs {#accessing_logs}

[Abhijay007]

we did something similar in Uptane, you can follow these docs here : https://docusaurus.io/docs/3.3.2/markdown-features/toc#heading-ids , let me know if this is something we want to do with the IDs

OK, so that appears to be as simple as converting this:

# Accessing management hub logs
{: #accessing_logs}

to this:

# Accessing management hub logs {#accessing_logs}

ya, I think the reference would work like this too, maybe we just need to edit the reference points to this {: #accessing_logs} to this {#accessing_logs}