Plan: Remove README.md Pattern and Implement Folder-First Navigation

Version: 1.0
Date: 2026-02-13
Status: Superseded
Related:

• Decision 01 Site Rendering Technology
• Plan 01 Governance Model & Content Structure
• Plan 02 Deployment and Hosting

1. Executive Summary

This plan eliminates the README.md convention from the content structure and modifies Quartz 4’s folder page rendering so that clicking a folder in the published site displays the content of the first file in that folder rather than an auto-generated navigation listing.

Problem: The current content structure places README.md files in every subfolder as “landing pages.” However, Quartz 4 does not treat README.md as a folder index — it renders at /folder/README/ as a standalone page. When users click a folder in the Explorer sidebar, they see an auto-generated listing page (from the FolderPage emitter), not the README content. This creates a confusing UX where README files exist but don’t serve their intended purpose. Additionally, value stream folders contain both a README.md (with rich content) and a stub 01 Overview.md, creating informational redundancy.

Solution: (A) Merge README.md content into 01 Overview.md files and remove all README.md files. (B) Modify Quartz’s FolderPage emitter to render the first published file’s content as the folder page.

Key Benefits:

• Eliminates confusing dual-page pattern (README + Overview)
• Folder clicks show meaningful content immediately instead of bare navigation lists
• Simpler, more intuitive content structure
• Fewer files to maintain; templates aligned with actual rendering behavior

Prerequisites:

• Quartz 4 development environment functional (npx quartz build works)
• Understanding of Quartz’s FolderPage emitter plugin and FolderContent component

2. Architecture / Context Overview

Current State

VS01 Lead to Cash/
├── README.md          ← Rich content (purpose, boundaries, stakeholders, etc.)
├── 01 Overview.md     ← Empty stub ("To Be Completed")
├── 02 Value Stream Map.md
├── ...

• README.md renders at URL /VS01-Lead-to-Cash/README/ — a standalone page
• Clicking “VS01 Lead to Cash” folder → auto-generated listing page showing child pages
• 01 Overview.md exists but has no content — the content it should have is in README.md

Proposed State

VS01 Lead to Cash/
├── 01 Overview.md     ← Contains merged content from former README.md
├── 02 Value Stream Map.md
├── ...

• Clicking “VS01 Lead to Cash” folder → renders 01 Overview.md content inline as the folder page
• No README.md anywhere in the content tree
• URL /VS01-Lead-to-Cash/ shows the Overview content directly

Tradeoffs

3. Implementation Steps

Step 1: Modify Quartz FolderPage Emitter — Render First File as Folder Page

Goal: When a folder page is generated and no explicit index.md exists for that folder, instead of showing a default “Folder: X” page with only the listing, show the content of the first published file in that folder (sorted alphabetically/numerically) followed by the folder listing.

File: quartz/plugins/emitters/folderPage.tsx

Changes to computeFolderInfo() function (lines 62-90):

The current logic:

1. Creates a default folder page with title “Folder: {name}” for each folder
2. Checks if any published content file’s simplified slug matches the folder path (i.e., an index.md)
3. If match found, uses that content instead

New logic — add a third step: if no index.md match was found, find the first file in the folder (by slug alphabetical order) and use its content:

function computeFolderInfo(
  folders: Set<SimpleSlug>,
  content: ProcessedContent[],
  locale: keyof typeof TRANSLATIONS,
): Record<SimpleSlug, ProcessedContent> {
  // Create default folder descriptions
  const folderInfo: Record<SimpleSlug, ProcessedContent> = Object.fromEntries(
    [...folders].map((folder) => [
      folder,
      defaultProcessedContent({
        slug: joinSegments(folder, "index") as FullSlug,
        frontmatter: {
          title: `${i18n(locale).pages.folderContent.folder}: ${folder}`,
          tags: [],
        },
      }),
    ]),
  );
 
  // Track which folders get an explicit index match
  const foldersWithExplicitIndex = new Set<SimpleSlug>();
 
  // Update with actual content if a file's slug matches the folder (index.md)
  for (const [tree, file] of content) {
    const slug = stripSlashes(simplifySlug(file.data.slug!)) as SimpleSlug;
    if (folders.has(slug)) {
      folderInfo[slug] = [tree, file];
      foldersWithExplicitIndex.add(slug);
    }
  }
 
  // For folders WITHOUT an explicit index, use the first file in the folder
  for (const folder of folders) {
    if (foldersWithExplicitIndex.has(folder)) continue;
 
    // Find all content files that are direct children of this folder
    const folderPrefix = folder + "/";
    const childFiles = content
      .filter(([, file]) => {
        const fileSlug = file.data.slug!;
        // Must start with folder path and NOT be in a deeper subfolder
        return (
          fileSlug.startsWith(folderPrefix) &&
          !fileSlug.slice(folderPrefix.length).includes("/")
        );
      })
      .sort(([, a], [, b]) => {
        // Sort by slug (alphabetical/numerical) — this respects the NN prefix convention
        return a.data.slug!.localeCompare(b.data.slug!);
      });
 
    if (childFiles.length > 0) {
      const [firstTree, firstFile] = childFiles[0];
      // Use the first file's content but keep the folder's index slug
      // so the URL remains /folder/ not /folder/first-file/
      const syntheticFile = { ...firstFile };
      syntheticFile.data = {
        ...firstFile.data,
        slug: joinSegments(folder, "index") as FullSlug,
      };
      folderInfo[folder] = [firstTree, syntheticFile];
    }
  }
 
  return folderInfo;
}

Important implementation notes:

• The FolderContent component (quartz/components/pages/FolderContent.tsx) already renders both content + a page listing below it (lines 99-119). No changes needed to that component — the folder page will show the first file’s content at the top, followed by the folder’s child page listing underneath.
• The Explorer sidebar folder click already navigates to /folder/index.html, so no sidebar changes needed.
• The sort by slug respects the NN numbering prefix convention (e.g., 01-Overview sorts before 02-Value-Stream-Map).

Verification:

1. Run npx quartz build and confirm no build errors
2. Check the generated /01-Value-Streams/VS01-Lead-to-Cash/index.html — it should contain the Overview content
3. Check that the folder listing still appears below the content
4. Verify the Explorer sidebar still works correctly (click folder → see content)

Deliverable: Modified folderPage.tsx with first-file-as-folder-page logic

Step 2: Content Consolidation — Merge README.md into 01 Overview.md for Value Streams

Goal: For each value stream folder, merge the rich content from README.md into 01 Overview.md and delete README.md.

Affected files (7 value stream folders):

For each folder, the process is:

1. If 01 Overview.md exists and is a stub, replace its content with the README content
2. If 01 Overview.md doesn’t exist, rename README.md to 01 Overview.md
3. Update frontmatter: change type: value-stream-readme → type: value-stream-overview
4. Transfer publish: true from README to 01 Overview where applicable
5. Remove the self-referencing “Value Stream Documentation” section’s [[01 Overview]] link (since the file IS the overview now) — or rephrase it
6. Delete README.md

Frontmatter adjustment example (VS01):

---
publish: true
page-status: draft
created: 2026-02-11
owner: vs-team-vs01-hthp-owner
vs-code: VS01
type: value-stream-overview # changed from value-stream-readme
---

Content adjustment: In the “Value Stream Documentation” section, remove or rephrase the self-reference:

## Value Stream Documentation
 
- ~~[[01 Overview]] - Detailed value stream description and context~~ (you are here)
- [[02 Value Stream Map]] - Visual flow diagram and stage definitions
  ...

Verification:

• Each value stream folder has exactly one overview file: 01 Overview.md
• No README.md files remain in value stream folders
• All content from former README is preserved in 01 Overview
• publish: true frontmatter correctly transferred

Deliverable: 7 consolidated 01 Overview.md files, 7 README.md files deleted

Step 3: Content Consolidation — Merge README.md into 01 Overview.md for Guilds

Goal: Same pattern as Step 2, but for guild folders.

Affected files (5 guild folders):

Frontmatter change: type: guild-readme → type: guild-overview

Verification:

• Each guild folder has 01 Overview.md with the former README content
• No README.md files remain in guild folders

Deliverable: 5 consolidated 01 Overview.md files, 5 README.md files deleted

Step 4: Content Consolidation — Merge README.md into 01 Overview.md for Practices

Goal: Same pattern for practice folders.

Affected practice folders (at least 13):

• GL01 Executive Guild/Practices/Strategy Mgmt/
• GL01 Executive Guild/Practices/Financial Mgmt/
• GL02 Sales Guild/Practices/Pipeline Mgmt/
• GL02 Sales Guild/Practices/Proposal Mgmt/
• GL03 Delivery Guild/Practices/Business Analysis/
• GL04 Technology Guild/Practices/Solution Eng/
• GL03 Delivery Guild/Practices/Project Mgmt/
• GL03 Delivery Guild/Practices/Product Mgmt/
• GL04 Technology Guild/Practices/Solution Eng/
• GL04 Technology Guild/Practices/Platform Architecture/
• GL04 Technology Guild/Practices/Release Management/
• GL05 Administration Guild/Practices/HR Management/ (has publish: true)
• GL05 Administration Guild/Practices/Training Management/ (if exists)
• GL05 Administration Guild/Practices/Communication Management/ (if exists)

Frontmatter change: type: practice-readme → type: practice-overview

Verification:

• Each practice folder has 01 Overview.md
• No README.md files remain in practice folders

Deliverable: ~13 consolidated 01 Overview.md files, ~13 README.md files deleted

Step 5: Remove Section-Level README.md Files

Goal: Delete section-level READMEs where an Index file already serves as the section overview.

Files to delete:

Before deleting: Verify that the Index files contain all essential information from the READMEs. Based on analysis:

• Value Stream Index.md covers all 7 value streams with descriptions, triggers, key practices, and governance — more comprehensive than the README
• Guild Index.md covers all 5 guilds with practices, purpose, and governance — more comprehensive than the README

Additional README files to delete:

• content/03 Products/NeuralOps/README.md — only 1 line, no useful content
• content/03 Products/NeuralOps/decisions/README.md — review and delete if redundant
• content/_99 Archive/README.md — in an ignored directory, low priority but clean up for consistency

Verification:

• No section-level README.md files remain
• Index files continue to serve as section landing pages

Deliverable: 4-5 section-level README.md files deleted

Step 6: Update All Internal Wiki-Links

Goal: Update all [[...README|...]] and [[...README]] wiki-links throughout the content to point to the new 01 Overview files instead.

Scope: 62 wiki-link references across the codebase that mention “README”. These fall into categories:

Category A — Value Stream README links (in Value Stream Index.md):

[[VS01 Lead to Cash/README|View Value Stream Details →]]
→ [[VS01 Lead to Cash/01 Overview|View Value Stream Details →]]

All 7 value stream links in Value Stream Index.md (lines 45, 66, 87, 106, 126, 147, 168).

Category B — Guild README links (in Guild Index.md):

[[GL01 Executive Guild/README|View Guild Details →]]
→ [[GL01 Executive Guild/01 Overview|View Guild Details →]]

All 5 guild links in Guild Index.md (lines 39, 55, 73, 90, 109).

Category C — Practice README links (in value stream README/Overview files):

[[02 Guilds/GL02 Sales Guild/Practices/Pipeline Mgmt/README|Pipeline Mgmt]]
→ [[02 Guilds/GL02 Sales Guild/Practices/Pipeline Mgmt/01 Overview|Pipeline Mgmt]]

~30 practice links across VS01-VS07 Overview files and guild Overview files.

Category D — Section-level README links:

[[README|Value Streams Overview]]  (in Value Stream Index.md line 195)
→ Remove or update to [[Value Stream Index|Value Streams Overview]]

Category E — References in governance/metadata docs:

• content/_metadata/Content Types.md line 211-213 — update prose about README convention
• content/00 Governance/02 Knowledge Standards.md line 199 — update “Guild README” → “Guild Overview” in the ownership table
• content/00 Governance/04 Decision Records.md line 196 — update prose
• content/index.md line 15 — update NeuralOps link

Category F — Template references:

• content/_templater/TMP00 Create Decision.md line 9 — update README reference

Verification:

• Run grep -r "README" content/ --include="*.md" — should return zero results (excluding .obsidian/ and _99 Archive/)
• All wiki-links resolve correctly (no broken links)
• Build the site and verify no 404s on internal navigation

Deliverable: All 62+ wiki-links updated, zero references to README.md in published content

Step 7: Update Templates

Goal: Update the Obsidian Templater templates so new content follows the new pattern (no README.md).

Files to modify:

Also update: The template content should specify output filename as 01 Overview.md instead of README.md (if the templater system uses filename conventions).

Verification:

• All template files renamed and content updated
• Creating a new value stream/guild/practice from template produces 01 Overview.md not README.md

Deliverable: 5 templates updated

Step 8: Update Documentation References

Goal: Update governance documents that describe the content structure to reflect the new pattern.

Files to update:

1. content/00 Governance/02 Knowledge Standards.md — Update ownership table (line 199: “Guild README” → “Guild Overview”)

2. content/00 Governance/04 Decision Records.md — Update prose about linking from “READMEs” (line 196)

3. content/_metadata/Content Types.md — Update or remove the “What about README files?” FAQ section (lines 211-213). Replace with documentation about the Overview pattern.

4. content/01 Value Streams/README.md Value Stream Structure section — This file is being deleted in Step 5, but if any of its structural documentation (lines 56-66 describing the folder structure with README.md) needs to be preserved elsewhere, add it to Value Stream Index.md.

Verification:

• No governance/metadata documents reference the README pattern
• Documentation accurately describes the 01 Overview.md convention

Deliverable: 3-4 governance documents updated

Step 9: Build, Verify, and Test

Goal: Validate the complete implementation.

Commands:

# Build the site
npx quartz build
 
# Verify no README references remain in published content
grep -r "README" content/ --include="*.md" | grep -v ".obsidian" | grep -v "_99 Archive"
 
# Start dev server for manual testing
npx quartz build --serve

Manual verification checklist:

• Site builds without errors
• Clicking “VS01 Lead to Cash” folder in Explorer shows Overview content (not a bare listing)
• Clicking any guild folder shows guild overview content
• Folder listing appears below the overview content on folder pages
• All internal wiki-links navigate correctly (no 404s)
• The 10 pages with publish: true all render correctly
• Breadcrumbs display correctly on folder pages
• Graph view shows correct connections (no orphaned README nodes)

Deliverable: Verified working site with no regressions

4. Decision Points & Options

Decision 1: How to Handle Folder Pages with No Published Children

Context: With ExplicitPublish() filter, many folders may have zero published files. The first-file-as-folder-page logic only works if at least one file in the folder has publish: true.

Options:

Recommendation: Option A — fall back to the default listing page. The proposed code already handles this (the if (childFiles.length > 0) guard means it only overrides when there IS a first file). This is the safest approach.

Decision 2: Sort Order for “First File” Selection

Context: The first file is determined by alphabetical slug sort. This works with the NN numbering convention (01, 02, 03…).

Risk: If a folder has files without number prefixes, the “first” file might not be the one intended as the overview.

Mitigation: The content structure already uses numbered prefixes everywhere. Document this as a convention requirement: “The first file in any folder (by alphanumeric sort) will be used as the folder landing page content.”

5. Risk Assessment

6. Success Criteria

1. Zero README.md files in any published content folder (excluding .obsidian/ and _99 Archive/)
2. Folder page navigation renders first file content inline when clicking any folder in the Explorer sidebar
3. Zero broken internal links — all former README wiki-links updated and resolving
4. All templates updated — new content creation follows 01 Overview.md pattern
5. Site builds cleanly with npx quartz build — no errors or warnings related to missing files
6. All 10 published pages continue to render correctly
7. Documentation updated — governance and metadata docs reflect the new convention

7. Appendices

Appendix A: Complete README.md File Inventory

Value Stream READMEs (7):

• content/01 Value Streams/VS01 Lead to Cash/README.md — publish: true
• content/01 Value Streams/VS02 Discovery to Deployment/README.md
• content/01 Value Streams/VS03 Request to Release/README.md
• content/01 Value Streams/VS04 Incident to Resolution/README.md
• content/01 Value Streams/VS05 Hire to High Performance/README.md
• content/01 Value Streams/VS06 Capability to Market/README.md
• content/01 Value Streams/VS07 Strategy to Execution/README.md

Guild READMEs (5):

• content/02 Guilds/GL01 Executive Guild/README.md
• content/02 Guilds/GL02 Sales Guild/README.md
• content/02 Guilds/GL03 Delivery Guild/README.md
• content/02 Guilds/GL04 Technology Guild/README.md — publish: true
• content/02 Guilds/GL05 Administration Guild/README.md

Practice READMEs (~13):

• content/02 Guilds/GL01 Executive Guild/Practices/Strategy Mgmt/README.md
• content/02 Guilds/GL01 Executive Guild/Practices/Financial Mgmt/README.md
• content/02 Guilds/GL02 Sales Guild/Practices/Pipeline Mgmt/README.md
• content/02 Guilds/GL02 Sales Guild/Practices/Proposal Mgmt/README.md
• content/02 Guilds/GL03 Delivery Guild/Practices/Business Analysis/README.md
• content/02 Guilds/GL04 Technology Guild/Practices/Solution Eng/README.md
• content/02 Guilds/GL03 Delivery Guild/Practices/Project Mgmt/README.md
• content/02 Guilds/GL03 Delivery Guild/Practices/Product Mgmt/README.md
• content/02 Guilds/GL04 Technology Guild/Practices/Solution Eng/README.md
• content/02 Guilds/GL04 Technology Guild/Practices/Platform Architecture/README.md
• content/02 Guilds/GL04 Technology Guild/Practices/Release Management/README.md
• content/02 Guilds/GL05 Administration Guild/Practices/HR Management/README.md — publish: true
• (Others if they exist — verify with glob before execution)

Section-Level READMEs (4-5):

• content/01 Value Streams/README.md
• content/02 Guilds/README.md
• content/03 Products/NeuralOps/README.md
• content/03 Products/NeuralOps/decisions/README.md
• content/_99 Archive/README.md (ignored directory, low priority)

Total: ~30 README.md files to process

Appendix B: Key Quartz Source Files

Appendix C: Key Decisions Summary