Docs: replace Jekyll Liquid keywords with MkDocs-friendly markdown

Abierto
  • ¿Algo no está bien?
#235 1 comentario 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
69/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
markdown
Área
documentation

Línea de trabajo

Start with docs/index.md, which is named as an example, then search the docs/ tree for {{site.data.keyword.*}}, Just the Docs {: …} markers, and Jekyll-only front matter. Replace or remove those items as requested and check that links remain valid relative to docs/; done when the docs no longer depend on those Jekyll features and the links still resolve.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Context

The Open Horizon documentation site is moving from Jekyll + Just the Docs to MkDocs Material, pulling this repository’s docs/ at build time into the Management Hub reference section (open-horizon/open-horizon.github.io#729). Pattern reference: open-horizon-services.github.io.

Until source markdown is cleaned up, the portal may substitute Liquid keywords and strip {: …} markers temporarily. Source content should not depend on that.

Problem

docs/ still contains Jekyll Liquid keyword usage (for example {{site.data.keyword.macOS_notm}} in docs/index.md) and Just-the-Docs-oriented front matter / markers. This repo also still pushes docs via CopyDocs; the portal now pulls at build time instead.

Ask
1. Clean up Markdown for MkDocs Material
  1. Replace {{site.data.keyword.*}} with plain text (for example macOS, Open Horizon).
  2. Remove any Just-the-Docs {: …} markers if present.
  3. Keep links valid relative to this repo’s docs/ tree.
2. Adjust YAML front matter (do not strip nav keys)

The portal builds the left nav from Just-the-Docs–compatible front matter across first-party and staged child-repo pages. For files under docs/:

Keep Drop (unused by MkDocs / portal)
title (nav label) layout
parent (nav hierarchy) has_children
nav_order (nav order) has_toc
Optional: description, copyright, years, lastupdated

Do not add repo_url / repo_name / repo_stars / repo_forks in source — the portal injects those at build time for the header source widget.

3. Remove CopyDocs GitHub Actions

Delete the push-based docs sync workflow; the portal clones this repo’s docs/ at build time into /docs/mgmt-hub/docs/:

Coordinate cutover with open-horizon.github.io#729.

4. Update docs/AGENTS.md for pull-at-build

Rewrite docs/AGENTS.md so it no longer describes CopyDocs push publishing. It should cover:

  1. Edit docs only in this repository’s docs/ tree.
  2. The portal pulls that tree at build time (destination /docs/mgmt-hub/docs/).
  3. Front matter rules from section 2 (title / parent / nav_order kept; layout / has_children / has_toc dropped).
  4. No Liquid / {: …} markers.
  5. Do not reintroduce CopyDocs / andstor/copycat-action.
References
Lenguaje dominante
Shell
Estrellas
12
Forks
46
Merge medio
5 d 12 h
PR fusionados (30 d)
3

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de open-horizon/devops

Todos los issues de open-horizon/devops

Issues similares

Más issues de Shell/Bash

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.