Skip to content

Import practitioner guides from wg-data-science submodule #34

Open
Titas-Ghosh wants to merge 2 commits into
chaoss:mainfrom
Titas-Ghosh:poc-practitioner-guides-import
Open

Import practitioner guides from wg-data-science submodule #34
Titas-Ghosh wants to merge 2 commits into
chaoss:mainfrom
Titas-Ghosh:poc-practitioner-guides-import

Conversation

@Titas-Ghosh
Copy link
Copy Markdown
Contributor

Summary

Imports the 11 practitioner guides + landing page from the upstream wg-data-science/practitioner-guides/ directory into the Hugo site, replacing the old WordPress-exported copies that contain broken Visual Composer shortcodes.

This follows the same submodule + module mount pattern established in #17 for CHAOSScon content.

Closes #27

What this PR does

  1. Git submodule: Adds external/wg-data-science pointing to https://github.com/chaoss/wg-data-science.git

  2. Hugo module mounts (hugo.toml):

    • Mounts each of the 11 guide markdown files + the landing page (website-landing.md) into content/
    • Mounts the images/ directory (29 PNGs) to static/practitioner-guides/images/
    • Re-declares default mounts for archetypes, content, and static (required by Hugo when adding any module mount)
  3. Cascade entries (hugo.toml): Sets title and url for each mounted guide page without modifying the upstream source files

  4. Render hooks (new files in themes/chaoss/layouts/_default/_markup/):

    • render-image.html — Rewrites GitHub blob image URLs (e.g., https://github.com/chaoss/wg-data-science/blob/main/practitioner-guides/images/foo.png) to local static paths (/practitioner-guides/images/foo.png)
    • render-link.html — Rewrites https://chaoss.community/practitioner-guide-* links to local relative paths so inter-guide navigation stays within the Hugo site. Uses an explicit allowlist of the 12 known local paths.
  5. Old WordPress copies: Marked draft: true to prevent duplicate pages. These can be deleted in a follow-up cleanup PR.

How it works

The upstream practitioner guide markdown files reference images using absolute GitHub blob URLs:

![Alt text](https://github.com/chaoss/wg-data-science/blob/main/practitioner-guides/images/bus-factor-bar-balanced.png)

And link to other guides using chaoss.community URLs:

[Practitioner Guide: Introduction](https://chaoss.community/practitioner-guide-introduction/)

Since we can't modify the upstream files, the render hooks transparently rewrite these at build time:

  • Image URLs → local /practitioner-guides/images/ static path
  • Guide links → local relative paths like /practitioner-guide-introduction/

Testing

  • Hugo build succeeds (520 pages, 425 static files)
  • All 29 images render correctly with rewritten src paths
  • All inter-guide links rewritten to local paths
  • Landing page links all point to local guide pages
  • External links (GitHub, YouTube, etc.) pass through unchanged
  • Old WordPress copies hidden via draft: true

Screenshots

Screenshot 2026-05-27 174522 Screenshot 2026-05-27 174850 Screenshot 2026-05-27 174942

- Add wg-data-science as git submodule under external/
- Mount 11 practitioner guide markdown files + landing page via
  Hugo module mounts in hugo.toml
- Mount images directory to static/practitioner-guides/images/
- Add cascade entries for titles and URLs of each guide
- Add render-image hook to rewrite GitHub blob image URLs to
  local static paths
- Add render-link hook to rewrite chaoss.community practitioner
  guide URLs to local relative paths
- Mark old WordPress-exported copies as draft: true to prevent
  duplicate pages

Closes chaoss#27

Signed-off-by: Titas-Ghosh <titas.ghosh7@gmail.com>
@Titas-Ghosh Titas-Ghosh force-pushed the poc-practitioner-guides-import branch from 78e0bf7 to f401d42 Compare May 27, 2026 12:29
@MoralCode
Copy link
Copy Markdown
Contributor

If they're being successfully imported at the same URLs, we dont need to keep the copies that are in this repo (the draft ones)

The imported guides from the wg-data-science submodule now serve
the same URLs, so the old copies (with broken Visual Composer
shortcodes) are no longer needed.

Signed-off-by: Titas-Ghosh <titas.ghosh7@gmail.com>
@Titas-Ghosh
Copy link
Copy Markdown
Contributor Author

Yeah that makes sense, removed all 12 old WordPress copies (11 guides + the landing page) the mounted versions serve the same URLs so they're no longer needed. 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Set up auto import of practitioner guide pages

2 participants