@sullux/markdown-docs 1.0.1 → 1.0.3

package/lib/layout.js

@@ -3,7 +3,26 @@ const { getCss } = require('./theme')
 const { getSearchScript } = require('./search')
 const { SVGS } = require('./icons')
 
-const calcRelativeHref = (currentHref, targetHref) => targetHref ? (path.relative(path.dirname(currentHref), targetHref.replace(/\.md$/, '.html')) || './') : '#'
+const normalizeTargetHref = (href) => {
+  if (!href) return '#'
+  if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('/') || href.startsWith('#') || href.startsWith('mailto:')) {
+    return href
+  }
+  return href
+    .replace(/(?:^|\/)README\.(?:md|html)(#.*)?$/i, (match) => match.replace(/README\.(?:md|html)/i, 'index.html'))
+    .replace(/\.md(#.*)?$/, (match) => match.replace(/\.md/, '.html'))
+}
+
+const calcRelativeHref = (currentHref, targetHref) => {
+  if (!targetHref) return '#'
+  const normalizedTarget = normalizeTargetHref(targetHref)
+  if (normalizedTarget.startsWith('http://') || normalizedTarget.startsWith('https://') || normalizedTarget.startsWith('/') || normalizedTarget.startsWith('#') || normalizedTarget.startsWith('mailto:')) {
+    return normalizedTarget
+  }
+  const normalizedCurrent = normalizeTargetHref(currentHref)
+  const rel = path.relative(path.dirname(normalizedCurrent), normalizedTarget)
+  return rel || './'
+}
 
 const renderNavTree = (items, currentHref) => {
   if (!items?.length) return ''
@@ -11,7 +30,7 @@ const renderNavTree = (items, currentHref) => {
   const flushGroup = () => {
     if (!group.length) return ''
     const list = `<ul class="nav-list">\n` + group.map((item) => {
-      const active = item.href === currentHref ? ' active' : ''
+      const active = normalizeTargetHref(item.href) === normalizeTargetHref(currentHref) ? ' active' : ''
       const href = calcRelativeHref(currentHref, item.href)
       const sub = item.children?.length ? renderNavTree(item.children, currentHref) : ''
       return `<li class="nav-item"><a href="${href}" class="nav-link${active}">${item.title}</a>${sub ? `<div class="nav-sub">${sub}</div>` : ''}</li>\n`
@@ -30,7 +49,12 @@ const renderNavTree = (items, currentHref) => {
 
 const renderTocList = (toc) => toc?.length ? `<div class="toc-title">On this page</div>\n<ul class="toc-list">\n` + toc.map((i) => `<li class="toc-item level-${i.level}"><a href="#${i.id}" class="toc-link" onclick="closeAllDrawers()">${i.title}</a></li>`).join('') + `</ul>\n` : ''
 
-const resolveAssetHref = (currentHref, assetPath) => (!assetPath || assetPath.startsWith('http') || assetPath.startsWith('<svg') || assetPath.startsWith('data:')) ? assetPath : calcRelativeHref(currentHref, assetPath.replace(/^\.\//, ''))
+const resolveAssetHref = (currentHref, assetPath) => {
+  if (!assetPath || assetPath.startsWith('http') || assetPath.startsWith('<svg') || assetPath.startsWith('data:') || assetPath.startsWith('/')) {
+    return assetPath
+  }
+  return calcRelativeHref(currentHref, assetPath.replace(/^\.\//, ''))
+}
 
 const renderSingleLogo = (logo, modeClass, title, currentHref) => logo ? (typeof logo === 'string' && logo.startsWith('<svg') ? logo : `<img src="${resolveAssetHref(currentHref, logo)}" alt="${title || 'Logo'}" class="${modeClass ? `brand-logo ${modeClass}` : 'brand-logo'}" />`) : ''
 
@@ -77,19 +101,11 @@ const renderPageLayout = ({ title, siteTitle, navTree, toc, contentHtml, current
   <div class="app-container">
     <aside id="sidebar-drawer" class="app-sidebar"><div class="drawer-header"><span class="drawer-title">Navigation</span><button class="drawer-close" onclick="closeAllDrawers()">${SVGS.close}</button></div><nav class="app-nav">${sidebarNav}</nav></aside>
     <main class="app-main"><article class="app-article">${contentHtml}</article></main>
-    <aside id="toc-drawer" class="app-toc">
-      <div class="drawer-header"><span class="drawer-title">Page Outline</span><button class="drawer-close" onclick="closeAllDrawers()">${SVGS.close}</button></div>
-      ${renderTocList(toc)}
-      <div class="theme-picker">
-        <button class="theme-opt" data-mode="light" onclick="setThemeMode('light')" title="Light">${SVGS.sun}</button>
-        <button class="theme-opt" data-mode="system" onclick="setThemeMode('system')" title="System">${SVGS.system}</button>
-        <button class="theme-opt" data-mode="dark" onclick="setThemeMode('dark')" title="Dark">${SVGS.moon}</button>
-      </div>
-    </aside>
+    <aside id="toc-drawer" class="app-toc"><div class="toc-container">${renderTocList(toc)}</div></aside>
   </div>
   <div id="drawer-backdrop" class="drawer-backdrop" onclick="closeAllDrawers()"></div>
-  ${getSearchScript()}
+  <script>${getSearchScript()}</script>
 </body></html>`
 }
 
-module.exports = { renderPageLayout, calcRelativeHref }
+module.exports = { calcRelativeHref, renderPageLayout }

package/lib/site.js

@@ -21,14 +21,25 @@ const collectMarkdownFiles = (dir, rootDir = dir) => {
   return files
 }
 
-const ensureIndexHtml = (outputDir, generatedPages) => {
-  if (generatedPages.some((p) => p === 'index.md')) return
-  const readmePath = path.join(outputDir, 'README.html'), indexPath = path.join(outputDir, 'index.html')
-  if (fs.existsSync(readmePath)) fs.copyFileSync(readmePath, indexPath)
-  else if (generatedPages.length > 0) {
-    const firstHtmlPath = path.join(outputDir, generatedPages[0].replace(/\.md$/, '.html'))
-    if (fs.existsSync(firstHtmlPath)) fs.copyFileSync(firstHtmlPath, indexPath)
+const extractFirstH1 = (ast) => {
+  for (const block of ast.blocks || []) {
+    if (block.type === 'header' && block.level === 1) {
+      return block.children ? block.children.map((c) => c.value || '').join('') : ''
+    }
   }
+  return ''
+}
+
+const normalizeHtmlPath = (relPath) => {
+  return relPath
+    .replace(/(?:^|\/)README\.md$/i, (match) => match.replace(/README\.md$/i, 'index.html'))
+    .replace(/\.md$/, '.html')
+}
+
+const rewriteMarkdownLinks = (html) => {
+  return html
+    .replace(/href="([^":#]*?)README\.md(#.*?)?"/gi, 'href="$1index.html$2"')
+    .replace(/href="([^":#]+)\.md(#.*?)?"/g, 'href="$1.html$2"')
 }
 
 const generateSite = (options = {}) => {
@@ -40,26 +51,38 @@ const generateSite = (options = {}) => {
 
   for (const file of mdFiles) {
     const rawMd = fs.readFileSync(file.fullPath, 'utf8')
-    const ast = parse(rawMd), toc = extractToc(ast), rawHtml = markdownToHtml(rawMd)
-    const contentHtml = rawHtml.replace(/href="([^":#]+)\.md(#.*?)?"/g, 'href="$1.html$2"')
-    const relHtmlPath = file.relPath.replace(/\.md$/, '.html'), outHtmlPath = path.join(config.output, relHtmlPath)
+    const ast = parse(rawMd)
+    const toc = extractToc(ast)
+    const rawHtml = markdownToHtml(rawMd)
+    const contentHtml = rewriteMarkdownLinks(rawHtml)
+    const relHtmlPath = normalizeHtmlPath(file.relPath)
+    const outHtmlPath = path.join(config.output, relHtmlPath)
 
     fs.mkdirSync(path.dirname(outHtmlPath), { recursive: true })
 
-    const pageTitle = config.title ? `${file.relPath.replace(/\.md$/, '')} - ${config.title}` : file.relPath.replace(/\.md$/, '')
+    const h1Title = extractFirstH1(ast)
+    const fallbackTitle = file.relPath.replace(/(?:^|\/)README\.md$/i, '').replace(/\.md$/, '') || config.title || 'Home'
+    const docTitle = h1Title || fallbackTitle
+    const pageTitle = config.title && docTitle !== config.title ? `${docTitle} - ${config.title}` : (docTitle || config.title)
 
     const fullHtml = renderPageLayout({
-      title: pageTitle, siteTitle: config.title,
-      navTree, toc, contentHtml, currentHref: file.relPath,
-      logo: config.logo, favicon: config.favicon, links: config.links, theme: config.theme,
+      title: pageTitle,
+      siteTitle: config.title,
+      navTree,
+      toc,
+      contentHtml,
+      currentHref: relHtmlPath,
+      logo: config.logo,
+      favicon: config.favicon,
+      links: config.links,
+      theme: config.theme,
     })
 
     fs.writeFileSync(outHtmlPath, fullHtml, 'utf8')
     const plainText = rawMd.replace(/[#*`_\[\]()\-]/g, ' ').replace(/\s+/g, ' ').trim()
-    searchIndex.push({ title: file.relPath.replace(/\.md$/, ''), href: relHtmlPath, content: plainText.slice(0, 300) })
+    searchIndex.push({ title: docTitle, href: relHtmlPath, content: plainText.slice(0, 300) })
   }
 
-  ensureIndexHtml(config.output, mdFiles.map((f) => f.relPath))
   fs.writeFileSync(path.join(config.output, 'search-index.json'), JSON.stringify(searchIndex, null, 2))
   copyAssets(config.input, config.output)
 

package/lib/summary.js

@@ -2,6 +2,14 @@ const fs = require('node:fs')
 const path = require('node:path')
 const { parse } = require('@sullux/markdown-compiler')
 
+const normalizeHref = (url) => {
+  if (!url) return '#'
+  if (url.startsWith('http://') || url.startsWith('https://') || url.startsWith('/') || url.startsWith('#')) return url
+  return url
+    .replace(/(?:^|\/)README\.md(#.*)?$/i, (match) => match.replace(/README\.md/i, 'index.html'))
+    .replace(/\.md(#.*)?$/, (match) => match.replace(/\.md/, '.html'))
+}
+
 const parseSummaryMd = (content) => {
   const ast = parse(content)
   const nav = []
@@ -18,7 +26,7 @@ const parseSummaryMd = (content) => {
         for (const node of itemNodes) {
           if (node.type === 'link') {
             const title = node.children ? node.children.map((c) => c.value || '').join('') : ''
-            listItems.push({ title, href: node.url, children: [] })
+            listItems.push({ title, href: normalizeHref(node.url), children: [] })
           }
         }
       }
@@ -49,8 +57,9 @@ const scanDir = (dir, rootDir = dir) => {
         items.push({ type: 'section', title, items: children })
       }
     } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'SUMMARY.md') {
-      const title = entry.name.replace(/\.md$/, '').replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
-      items.push({ title, href: relPath, children: [] })
+      const isReadme = /^README\.md$/i.test(entry.name)
+      const title = isReadme ? 'Overview' : entry.name.replace(/\.md$/, '').replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
+      items.push({ title, href: normalizeHref(relPath), children: [] })
     }
   }
 
@@ -65,4 +74,4 @@ const getNavigationTree = (inputDir) => {
   return scanDir(inputDir)
 }
 
-module.exports = { parseSummaryMd, scanDir, getNavigationTree }
+module.exports = { normalizeHref, parseSummaryMd, scanDir, getNavigationTree }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sullux/markdown-docs",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A zero-dependency, local-first static documentation site generator compiling GitBook-style Markdown docs.",
   "main": "./index.js",
   "bin": {