fix: support Jinja2 include-markdown directives for blank documentation pages #485

[rudy128]

📌 Fixes
Fixes #485
Fixes #3565

📝 Summary of Changes
Fixed blank documentation pages caused by unsupported MkDocs-style Jinja2 {% include-markdown %} directives in the Nextra/Next.js framework.

Problem

Several documentation pages were rendering completely blank on the live site because they used MkDocs-style {% include-markdown %} directives that were not supported by Nextra. Affected pages included:

• /docs/contribution-guidelines/security/security-inc
• /docs/contribution-guidelines/security/security_contacts-inc
• /docs/contribution-guidelines/coc-inc
• /docs/contribution-guidelines/onboarding-inc
• /docs/contribution-guidelines/contributing-inc
• Other pages using include directives

Solution

Implemented support for Jinja2-style include directives in src/app/docs/[...slug]/page.tsx:

Changes Made

• ✅ Added processInclude() helper function to handle all include directive processing with common logic
• ✅ Implemented support for three types of include directives:
  1. Jekyll-style: {% include "path" %}
  2. Partial includes with markers: {% include-markdown "path" start="<!--marker-->" end="<!--marker-->" %}
  3. Full includes: {% include-markdown "path" %}
• ✅ Support for both single-line and multi-line Jinja2 syntax
• ✅ Handle empty markers (includes entire file when start="" and end="")
• ✅ Fallback to repository root when files not found in docs/content/ directory
• ✅ Extract content between HTML comment markers when specified
• ✅ Clean, maintainable code with reduced duplication (~80 lines removed)

Technical Details

• Uses regex patterns with [\s\S]*? to match multi-line Jinja2 directives
• Processes partial includes first to avoid conflicts with full include regex
• Automatically removes HTML comments from included content
• Resolves relative paths correctly (e.g., ../../../CONTRIBUTING.md)
• Gracefully handles missing files with user-friendly error messages

Checklist

• I have reviewed the project's contribution guidelines.
• I have tested the changes locally and ensured they work as expected.
• My code follows the project's coding standards.
• All previously blank pages now render with correct content
• No console errors or warnings

Screenshots or Logs (if applicable)

✅ All affected pages now display content correctly
✅ Include directives properly resolved and content extracted
✅ Pages load successfully without errors

👀 Reviewer Notes

• Solution works with existing markdown files without requiring any markdown changes
• Supports the exact Jinja2 syntax that was used in the original MkDocs setup
• Code is refactored into a reusable processInclude() function for maintainability
• No breaking changes to existing functionality

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign vedansh-5 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✅ Deploy Preview for kubestellar-docs ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	d5e117c
🔍 Latest deploy log	https://app.netlify.com/projects/kubestellar-docs/deploys/69681ec674746700082cbdd3
😎 Deploy Preview	https://deploy-preview-704--kubestellar-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

Welcome to KubeStellar! 🚀 Thank you for submitting this Pull Request.

Before your PR can be merged, please ensure:

✅ DCO Sign-off - All commits must be signed off with git commit -s to certify the Developer Certificate of Origin

✅ PR Title - Must start with an emoji: ✨ (feature), 🐛 (bug fix), 📖 (docs), 🌱 (infra/tests), ⚠️ (breaking change)

Getting Started with KubeStellar:

• 📦 Quick Start
• 📖 Documentation
• 🎬 YouTube - Getting Started & Contributing

Contributor Resources:

• 📚 Contributor Handbook
• 🪜 Contributor Ladder
• 🎓 Mentorship Programs (LFX, GSoC)
• 💬 Slack - #kubestellar-dev

---

🌟 Help KubeStellar Grow - We Need Adopters!

Our roadmap is driven entirely by adopter feedback. Whether you're using KubeStellar yourself or know someone who could benefit from multi-cluster Kubernetes:

📋 Take our Multi-Cluster Survey - Share your use cases and help shape our direction!

---

A maintainer will review your PR soon. Feel free to ask questions in the comments or on Slack!

[kubestellar-prow]

Hi @rudy128. Thanks for your PR.

I'm waiting for a kubestellar member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[rudy128]

@naman9271 @oksaumya please review and merge the pr

[github-actions]

📖 Preview Links

The following documentation pages were changed in this PR:

Status	Page	Preview Link
📝 modified	security_contacts-inc	View preview

---

🔗 Full preview site