Skip to content

docs: make knowledge base generic and refine header navigation - #8

Merged
EdwinPhilip merged 3 commits into
mainfrom
design/refine-header-navigation
Oct 25, 2026
Merged

EdwinPhilip merged 3 commits into
mainfrom
design/refine-header-navigation

Conversation

@EdwinPhilip

@EdwinPhilip EdwinPhilip commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner

Public documentation audit and navigation refinement

This builds on the original header redesign and the request to make the complete public knowledge base general-purpose engineering education rather than employer-specific or interview preparation. It remains in PR #8; no changes are merged automatically.

Content audit scope and outcome

  • Reviewed and edited all 94 Markdown files under docs/guides/, across networking, Linux, Kubernetes, Terraform, GCP, GKE, cloud reliability and platform engineering.
  • Reframed chapter prompts from Interviewer to neutral engineering focus; removed Q1-style article headings and spoken answer sections, replacing them with engineering problems and practical takeaways.
  • Converted challenge banks from interview presentation to advanced technical FAQs with their full detailed explanations. Kept existing follow-ups.md URLs for link compatibility.
  • Removed hypothetical first-person interview-answer framing; retained genuine technical mechanisms, commands, configurations, diagrams, scenarios, trade-offs and citations.
  • Scanned for private company/project and personal employment claims. No Catawiki, HackerRank or personal-project references remain in the public guides.
  • Adjusted the knowledge-base landing text and the portfolio homepage's description of its guides to match the educational framing.
  • Portfolio boundary: docs/about.md and the experience/biography sections of docs/index.md remain intentionally personal, because those pages serve as the author's professional portfolio. The engineering guides do not narrate that experience.

Automated regression prevention

  • Added scripts/audit-public-guides.mjs and npm run docs:audit.
  • PR workflow now runs the audit before npm run docs:build.
  • Checks forbidden employer/interview framing, personal-work statements, numbered question-style article headings, relative Markdown links, code-fence balance, and declared FAQ bank count.
  • Audit intentionally excludes portfolio Home/About content.

Existing header change in this PR

  • Primary header links Home · Guides · About me, with GitHub and LinkedIn as compact VitePress social icons.
  • Desktop rounded navigation grouping, keyboard focus, reduced-motion support and unchanged mobile navigation.
  • Preserves all existing guides, sidebar hierarchy, Mermaid integration and GitHub Pages base path.

Changed paths

  • 94 Markdown files in docs/guides/ (complete guide corpus).
  • docs/index.md (one public-guide-description sentence only).
  • docs/.vitepress/config.mts, docs/.vitepress/theme/custom.css.
  • scripts/audit-public-guides.mjs (new).
  • package.json.
  • .github/workflows/pr-build.yml.
  • No changes to docs/about.md or production deployment workflow.

Verification

  • All 94 guide files scanned and retained; original diagrams and code blocks preserved during editorial edits.
  • Branch is up to date with main; 100 total changed files.
  • CI: See the latest Actions run for public guide audit and full VitePress build. Do not infer successful validation until both steps complete.
  • Visual screenshot inspection after merge remains separate from Markdown/VitePress build validation.

Expected site

https://edwinphilip.github.io/

Please review the changed guide tone and the header. Do not merge automatically.

@EdwinPhilip EdwinPhilip changed the title design: refine portfolio header with Guides and compact social navigation docs: make knowledge base generic and refine header navigation Oct 25, 2026
@EdwinPhilip
EdwinPhilip merged commit 8985a11 into main Oct 25, 2026
1 check passed
@EdwinPhilip
EdwinPhilip deleted the design/refine-header-navigation branch October 25, 2026 13:19
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.

1 participant