Google OKF and GitHub Pages

[sualeh]

I want to render a Google OKF bundle in GitHub Pages. They are mostly compatible in that I can add in additional tags for GitHub Pages where needed. The real difference is in the indexes. Google OKF specifies not YAML front-matter in the indexes, whereas GitHub Pages prefers organization of children pages with "children" and "childGroups". It would be good to have a tooling ecosystem by affording tool inter-operability.

Is this something that can be addressed in the next version of Google OKF? Either by:

1. Allowing YAML front-matter in index pages.
2. Or, standardizing on "children" and "childGroups" in index pages.

[straumat]

Maybe my project Kiso can be interesting for you.
It builds a website (html) along the markdown files and it creates the missing index.md files (it also generates a sitemap.xml and llms.txt).
This is how the google exemple renders with it on github pages : https://oak-invest.github.io/kiso/examples/kb-google-example/

[sualeh]

Thanks, @straumat I will check out your project.

My point is no that the index files are missing, but that they do not render well in GitHub Pages sites.

[Jeanish]

hey @sualeh , ran into this too while messing around with an OKF bundle on pages.

tbh i don't think we should touch Section-6 for this no frontmatter in index.md is kind of core to the spec and changing it breaks conformance for everyone already using it. feels like the actual fix belongs outside the spec, not in it.

was thinking a small converter that takes a normal OKF bundle and spits out a jekyll-ready version alongside it walks the folder structure + existing concept frontmatter and auto-fills nav_order/has_children/parent etc. original bundle stays untouched, still fully spec-compliant.

gonna try building a rough version of this, will post here if it works.