feat: Use README.md as placeholder pages for sections

Implemented automatic detection and use of README.md files as section
placeholder pages in Confluence. This provides a much better user
experience than using the first child page to represent a section.

How it works:
1. After parsing nav, detect sections and their children
2. Infer section directory from children's file paths
3. Look for README.md in that directory
4. If found, create a page for it with the section title
5. Use README page as parent for section children
6. Prioritize README pages by sorting them first during sync

Example:
  docs/
    subscriptions/
      README.md          ← Becomes "Subscriptions" page
      overview.md
      development/
        README.md        ← Becomes "Development" page
        arch.md

Result in Confluence:
  Home
  └─ Subscriptions (from subscriptions/README.md)
     ├─ Overview
     └─ Development (from subscriptions/development/README.md)
        └─ Architecture

Benefits:
- Section pages have meaningful content from README.md
- Better matches MkDocs/GitHub documentation patterns
- Falls back to first child if no README.md exists
- Fully backward compatible

All tests passing (148/148).

Author: agpenton

dist/index.js

@@ -114,7 +114,7 @@ async function findParentPage() {
  */
 async function syncPages(home, localPages, sectionHierarchy, renderer) {
     // Map to track synced page IDs
-    // For sections, we store the ID of the first page that represents that section
+    // For sections, we store the ID of the section's README or first page
     const syncedPages = new Map();
     syncedPages.set(null, home); // root level pages use home as parent
 
@@ -134,7 +134,7 @@ async function syncPages(home, localPages, sectionHierarchy, renderer) {
         const pages = pagesByParent.get(sectionName) || [];
 
         // Find the parent page ID for this section
-        // If the section has a parent section, use the ID of that parent section's first page
+        // If the section has a parent section, use the ID of that parent section's page
         // Otherwise, use the home page
         const parentSectionName = sectionHierarchy[sectionName] || null;
         const parentPageId = syncedPages.get(parentSectionName);
@@ -164,12 +164,21 @@ async function syncPages(home, localPages, sectionHierarchy, renderer) {
             union.push(remotePage);
         }
 
+        // Sort pages to prioritize README.md (section placeholder) first
+        union.sort((a, b) => {
+            const aIsReadme = a.meta?.path?.endsWith('README.md') || false;
+            const bIsReadme = b.meta?.path?.endsWith('README.md') || false;
+            if (aIsReadme && !bIsReadme) return -1;
+            if (!aIsReadme && bIsReadme) return 1;
+            return 0;
+        });
+        
         // Sync all pages at this level
         for (let i = 0; i < union.length; i++) {
             const page = union[i];
             const syncedPage = await page.sync(renderer, confluence);
 
-            // The first page in this section represents the section
+            // The first page (preferably README) represents the section
             // Store its ID so child sections can reference it
             // Don't overwrite the root level (null) which is set to home page ID
             if (i === 0 && sectionName !== null && syncedPage && syncedPage.id) {

dist/index.js.map

@@ -99,6 +99,13 @@ function getContext(basePath = '.') {
     const sectionHierarchy = new Map();
     const pages = traverse(repo_url, nav, basePath, [], null, sectionHierarchy);
     const readMe = getPage(repo_url, site_name, path.resolve(basePath, README_MD), '');
+    
+    // Create README.md pages for sections
+    const sectionPages = createSectionPages(repo_url, basePath, pages, sectionHierarchy);
+    
+    // Add section pages to the main pages array
+    pages.push(...sectionPages);
+    
     const pageRefs = pages.reduce((obj, page) => {
         obj[page.meta.path] = page.title;
         return obj;
@@ -118,4 +125,88 @@ function getContext(basePath = '.') {
     return context;
 }
 
+/**
+ * Create pages for section README.md files
+ * 
+ * @param {string} repo_url - Repository URL
+ * @param {string} basePath - Base path to resolve files
+ * @param {Array<LocalPage>} pages - Array of pages
+ * @param {Map} sectionHierarchy - Section hierarchy map
+ * @returns {Array<LocalPage>} Array of section README pages
+ */
+function createSectionPages(repo_url, basePath, pages, sectionHierarchy) {
+    const sectionPages = [];
+    
+    // For each section, try to find its README.md
+    for (let [sectionName, parentSection] of sectionHierarchy.entries()) {
+        // Find all pages that belong to this section
+        const sectionChildren = pages.filter(p => p.parentPath === sectionName);
+        
+        if (sectionChildren.length === 0) continue;
+        
+        // Infer the section directory from children's paths
+        const sectionDir = inferSectionDirectory(sectionChildren);
+        
+        if (sectionDir) {
+            // Try to find README.md in this directory
+            const readmePath = path.resolve(basePath, 'docs', sectionDir, 'README.md');
+            const readmePage = getPage(repo_url, sectionName, readmePath, config.confluence.titlePrefix);
+            
+            if (readmePage) {
+                readmePage.parentPath = parentSection;
+                sectionPages.push(readmePage);
+                logger.debug(`Created section page "${sectionName}" from ${sectionDir}/README.md`);
+            }
+        }
+    }
+    
+    return sectionPages;
+}
+
+/**
+ * Infer the common directory path from a section's children
+ * 
+ * @param {Array<LocalPage>} children - Array of child pages
+ * @returns {string|null} Common directory path or null
+ */
+function inferSectionDirectory(children) {
+    if (children.length === 0) return null;
+    
+    // Get relative paths of all children from their absolute paths
+    const relativePaths = children.map(child => {
+        const fullPath = child.meta.path;
+        // Find 'docs/' in the path and get everything after it
+        const docsIndex = fullPath.indexOf('/docs/');
+        if (docsIndex === -1) return null;
+        
+        const afterDocs = fullPath.substring(docsIndex + 6); // +6 for '/docs/'
+        // Get the directory part (remove filename)
+        return path.dirname(afterDocs);
+    }).filter(p => p !== null);
+    
+    if (relativePaths.length === 0) return null;
+    
+    // Find common prefix directory
+    const firstPath = relativePaths[0];
+    
+    // If all paths are the same, return that path
+    if (relativePaths.every(p => p === firstPath)) {
+        return firstPath;
+    }
+    
+    // Find longest common prefix
+    const parts = firstPath.split(path.sep);
+    
+    for (let len = parts.length; len > 0; len--) {
+        const prefix = parts.slice(0, len).join(path.sep);
+        const allMatch = relativePaths.every(p => p.startsWith(prefix));
+        
+        if (allMatch) {
+            return prefix;
+        }
+    }
+    
+    return null;
+}
+
 export default { getContext };

lib/confluence-syncer.js

@@ -0,0 +1 @@
+# Home

lib/context.js

@@ -0,0 +1,3 @@
+# Subscriptions
+
+This is the subscriptions section overview.

test/fixtures/samples/with_section_readmes/docs/index.md

@@ -0,0 +1,3 @@
+# Development Environment
+
+Development environment details.

test/fixtures/samples/with_section_readmes/docs/subscriptions/README.md

@@ -0,0 +1 @@
+# Development Architecture

test/fixtures/samples/with_section_readmes/docs/subscriptions/development/README.md

@@ -0,0 +1 @@
+# Overview

test/fixtures/samples/with_section_readmes/docs/subscriptions/development/arch.md

@@ -0,0 +1,9 @@
+site_name: Test With Section READMEs
+repo_url: https://github.com/test/repo
+
+nav:
+  - Home: index.md
+  - Subscriptions:
+      - Overview: subscriptions/overview.md
+      - Development:
+          - Dev Arch: subscriptions/development/arch.md