@docsector/docsector-reader 1.6.0 → 1.7.1

package/README.md

@@ -41,6 +41,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 ## ✨ Features
 
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
+- 🧱 **Raw HTML in Markdown** — Renders inline and block HTML tags inside markdown sections (including homepage remote README content)
 - 🧩 **Mermaid Diagrams** — Native support for fenced ` ```mermaid ` blocks, with automatic dark/light theme switching
 - 🚨 **GitHub-Style Alerts** — Native support for `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`
 - 🌍 **Internationalization (i18n)** — Multi-language support with HJSON locale files and per-page translations
@@ -58,6 +59,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🔐 **Web Bot Auth** — Can publish a signed HTTP message signatures directory and includes helpers to sign outbound bot requests
 - 🧭 **Content Signals** — Injects `Content-Signal` policy in `robots.txt` with deterministic, idempotent build output
 - 🏠 **Markdown Home at Root** — Homepage is rendered from `src/pages/Homepage.{lang}.md` directly at `/`
+- 🌍 **Remote README as Home** — Optional build-time remote README source for homepage with automatic local fallback
+- 🧬 **Scaffolded Homepage Override Wiring** — New consumer projects automatically wire `virtual:docsector-homepage-override` into i18n message building
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
 - 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
 - ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`
@@ -333,6 +336,39 @@ Set any target to `null` or `false` to disable that relation.
 
 ---
 
+## 🏠 Remote README as Home
+
+You can configure Docsector Reader to use a remote README as homepage content.
+
+- Fetch happens at build-time.
+- The same README content is used for all configured languages.
+- If fetch fails, it falls back to local `src/pages/Homepage.{lang}.md` by default.
+
+### Configure
+
+```javascript
+export default {
+  // ...other config
+
+  homePage: {
+    source: 'remote-readme',
+    remoteReadmeUrl: 'https://raw.githubusercontent.com/your-org/your-repo/main/README.md',
+    timeoutMs: 8000,
+    fallbackToLocal: true
+  }
+}
+```
+
+### Validate
+
+```bash
+npx docsector build
+cat dist/spa/homepage.md
+cat dist/spa/homepage.en-US.md
+```
+
+---
+
 ## 🔐 Web Bot Auth
 
 Docsector Reader can publish a signed Web Bot Auth directory at:
@@ -733,6 +769,7 @@ Consumer projects use the `buildMessages` helper from the engine:
 
 ```javascript
 import { buildMessages } from '@docsector/docsector-reader/i18n'
+import homePageOverride from 'virtual:docsector-homepage-override'
 
 const langModules = import.meta.glob('./languages/*.hjson', { eager: true })
 const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?raw', import: 'default' })
@@ -740,7 +777,7 @@ const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?r
 import boot from 'pages/boot'
 import pages from 'pages'
 
-export default buildMessages({ langModules, mdModules, pages, boot })
+export default buildMessages({ langModules, mdModules, pages, boot, homePageOverride })
 ```
 
 ### Language files

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '1.6.0'
+const VERSION = '1.7.1'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -165,6 +165,16 @@ export default {
   //   }
   // },
 
+  // @ Home page source (optional)
+  // Use a remote README.md as homepage content at build-time.
+  // Falls back to local src/pages/Homepage.{lang}.md on fetch failure by default.
+  // homePage: {
+  //   source: 'remote-readme', // 'local' | 'remote-readme'
+  //   remoteReadmeUrl: 'https://raw.githubusercontent.com/your-org/your-repo/main/README.md',
+  //   timeoutMs: 8000,
+  //   fallbackToLocal: true
+  // },
+
   // @ Homepage Link headers for agent discovery (optional)
   // linkHeaders: {
   //   enabled: true,
@@ -254,6 +264,7 @@ const TEMPLATE_CSS_STUB = `\
 const TEMPLATE_I18N_INDEX = `\
 // @ Import i18n message builder from Docsector Reader
 import { buildMessages } from '@docsector/docsector-reader/i18n'
+import homePageOverride from 'virtual:docsector-homepage-override'
 
 // @ Import language HJSON files (Vite-compatible eager import)
 const langModules = import.meta.glob('./languages/*.hjson', { eager: true })
@@ -264,7 +275,7 @@ const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?r
 import boot from 'pages/boot'
 import pages from 'pages'
 
-export default buildMessages({ langModules, mdModules, pages, boot })
+export default buildMessages({ langModules, mdModules, pages, boot, homePageOverride })
 `
 
 const TEMPLATE_I18N_HJSON = `\

package/docsector.config.js

@@ -43,6 +43,14 @@ export default {
     toolSuffix: 'docsector'
   },
 
+  // @ Home page source
+  homePage: {
+    source: 'remote-readme',
+    remoteReadmeUrl: 'https://raw.githubusercontent.com/docsector/docsector-reader/main/README.md',
+    timeoutMs: 8000,
+    fallbackToLocal: true
+  },
+
   // @ Languages
   languages: [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",

package/src/components/DPageBar.vue

@@ -71,6 +71,13 @@ const rawMarkdown = computed(() => {
 
 const markdownURL = computed(() => {
   if (store.state.page.base === 'home') {
+    const homePage = docsectorConfig.homePage || {}
+    const isRemoteHome = homePage.source === 'remote-readme' && typeof homePage.remoteReadmeUrl === 'string' && homePage.remoteReadmeUrl.length > 0
+
+    if (isRemoteHome) {
+      return homePage.remoteReadmeUrl
+    }
+
     return `/Homepage.${locale.value}.md`
   }
 
@@ -87,12 +94,27 @@ const fullMarkdownURL = computed(() => {
   return `${window.location.origin}${path}.md`
 })
 
+const chatSourceURL = computed(() => {
+  if (store.state.page.base !== 'home') {
+    return fullMarkdownURL.value
+  }
+
+  const homePage = docsectorConfig.homePage || {}
+  const isRemoteHome = homePage.source === 'remote-readme' && typeof homePage.remoteReadmeUrl === 'string' && homePage.remoteReadmeUrl.length > 0
+
+  if (isRemoteHome) {
+    return `${window.location.origin}/`
+  }
+
+  return fullMarkdownURL.value
+})
+
 const chatgptURL = computed(() => {
-  const prompt = `Read ${fullMarkdownURL.value} and answer questions about the content.`
+  const prompt = `Read ${chatSourceURL.value} and answer questions about the content.`
   return `https://chat.openai.com/?q=${encodeURIComponent(prompt)}`
 })
 const claudeURL = computed(() => {
-  const prompt = `Read ${fullMarkdownURL.value} and answer questions about the content.`
+  const prompt = `Read ${chatSourceURL.value} and answer questions about the content.`
   return `https://claude.ai/new?q=${encodeURIComponent(prompt)}`
 })
 

package/src/components/DPageMeta.vue

@@ -157,11 +157,19 @@ const next = computed(() => {
 
   return ''
 })
+
+const hideRemoteHomeFooterMeta = computed(() => {
+  const homePage = docsectorConfig.homePage || {}
+  const isRemoteHome = homePage.source === 'remote-readme' && typeof homePage.remoteReadmeUrl === 'string' && homePage.remoteReadmeUrl.length > 0
+  const isHomePage = route.path === '/' || store.state.page.base === 'home'
+
+  return isRemoteHome && isHomePage
+})
 </script>
 
 <template>
 <div id="d-page-meta">
-  <div class="row justify-between q-mt-lg">
+  <div v-if="!hideRemoteHomeFooterMeta" class="row justify-between q-mt-lg">
     <div id="d-page-edit" class="col">
       <q-btn dense no-caps text-color="black" :color="color" @click="openURL(URL)" aria-label="Edit page on Github">
         <q-icon class="q-mr-xs" name="fab fa-github" size="20px" />

package/src/components/DPageSection.vue

@@ -130,16 +130,21 @@ const tokenized = computed(() => {
 
   const { source: sourceWithQuickLinks, quickLinksMap } = extractQuickLinksBlocks(normalizedSource)
 
-  const Markdown = new MarkdownIt()
+  const Markdown = new MarkdownIt({
+    // Home remote README may contain raw HTML blocks (badges, centered headers, etc.)
+    html: true
+  })
   Markdown.use(attrs, {
     leftDelimiter: ':',
     rightDelimiter: ';',
     allowedAttributes: ['filename']
   })
 
-  // Use a plain inline renderer to avoid markdown-it-attrs edge cases
-  // when rendering isolated inline fragments.
-  const MarkdownInline = new MarkdownIt()
+  // Keep inline rendering aligned with block parsing so raw HTML inline
+  // fragments (e.g. <b>, <a>) are rendered instead of escaped.
+  const MarkdownInline = new MarkdownIt({
+    html: true
+  })
 
   const markdownEnv = {}
 
@@ -323,6 +328,12 @@ const tokenized = computed(() => {
           })
           break
         }
+        case 'html_block':
+          tokens.push({
+            tag: 'html',
+            content: element.content
+          })
+          break
       }
     } else if (level === 1) {
       const parent = tokens[tokens.length - 1]
@@ -370,6 +381,10 @@ const tokenized = computed(() => {
         case 'inline':
           parent.content += element.content
           break
+        case 'html_inline':
+        case 'html_block':
+          parent.content += element.content
+          break
 
         case 'list_item_close':
           parent.content += '</li>'
@@ -450,6 +465,11 @@ const tokenized = computed(() => {
       <table v-html="token.content"></table>
     </div>
 
+    <div
+      v-else-if="token.tag === 'html'"
+      v-html="token.content"
+    ></div>
+
     <p
       v-else-if="token.tag === 'p'"
       v-html="token.content"

package/src/css/app.sass

@@ -1,7 +1,7 @@
 /* --- Docsector Reader --- */
 @font-face
   font-family: "Fira Code Nerd Font"
-  src: url('/fonts/FiraCodeNerdFont-Regular.ttf') format('truetype')
+  src: local('Fira Code Nerd Font'), local('FiraCode Nerd Font')
   font-weight: normal
   font-style: normal
 // * General

package/src/i18n/helpers.js

@@ -117,9 +117,10 @@ export function filter (source) {
  * @param {Object} options.pages - Page registry from pages/index.js
  * @param {Object} options.boot - Boot meta from pages/boot.js
  * @param {string[]} [options.langs] - Language codes to process (auto-detected from langModules if omitted)
+ * @param {Object<string,string>} [options.homePageOverride] - Optional per-language Home markdown override
  * @returns {Object} Complete i18n messages object keyed by locale
  */
-export function buildMessages ({ langModules, mdModules, pages, boot, langs }) {
+export function buildMessages ({ langModules, mdModules, pages, boot, langs, homePageOverride = {} }) {
   // Auto-detect languages from HJSON files if not provided
   if (!langs) {
     langs = Object.keys(langModules).map(key => {
@@ -145,6 +146,11 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs }) {
   }
 
   function loadHomepage (lang) {
+    const override = homePageOverride?.[lang] ?? homePageOverride?.['en-US']
+    if (typeof override === 'string' && override.length > 0) {
+      return filter(override)
+    }
+
     const key = `../pages/Homepage.${lang}.md`
     const fallbackKey = '../pages/Homepage.en-US.md'
 
@@ -159,6 +165,23 @@ export function buildMessages ({ langModules, mdModules, pages, boot, langs }) {
   }
 
   function extractHeadingFromHomepage (lang) {
+    const override = homePageOverride?.[lang] ?? homePageOverride?.['en-US']
+    if (typeof override === 'string' && override.length > 0) {
+      const htmlHeadingMatch = override.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i)
+      if (htmlHeadingMatch) {
+        const htmlHeading = htmlHeadingMatch[1]
+          .replace(/<[^>]+>/g, ' ')
+          .replace(/\s+/g, ' ')
+          .trim()
+        if (htmlHeading) {
+          return htmlHeading
+        }
+      }
+
+      const overrideMatch = override.match(/^#\s+(.+)$/m)
+      return overrideMatch ? overrideMatch[1].trim() : ''
+    }
+
     const key = `../pages/Homepage.${lang}.md`
     const fallbackKey = '../pages/Homepage.en-US.md'
 

package/src/i18n/index.js

@@ -1,5 +1,6 @@
 // @ Import i18n message builder
 import { buildMessages } from './helpers'
+import homePageOverride from 'virtual:docsector-homepage-override'
 
 // @ Import language HJSON files (Vite-compatible eager import)
 const langModules = import.meta.glob('./languages/*.hjson', { eager: true })
@@ -10,4 +11,4 @@ const mdModules = import.meta.glob('../pages/**/*.md', { eager: true, query: '?r
 import boot from 'pages/boot'
 import pages from 'pages'
 
-export default buildMessages({ langModules, mdModules, pages, boot })
+export default buildMessages({ langModules, mdModules, pages, boot, homePageOverride })

package/src/index.js

@@ -98,6 +98,11 @@
  * @param {boolean} [config.webMcp.tools.getPage=true] - Enables tool get_page
  * @param {boolean} [config.webMcp.tools.navigateTo=true] - Enables tool navigate_to
  * @param {boolean} [config.webMcp.tools.copyCurrentPage=true] - Enables tool copy_current_page
+ * @param {Object} [config.homePage] - Home page content source settings
+ * @param {'local'|'remote-readme'} [config.homePage.source='local'] - Source strategy for home page markdown
+ * @param {string|null} [config.homePage.remoteReadmeUrl=null] - Absolute URL of remote README markdown when source is remote-readme
+ * @param {number} [config.homePage.timeoutMs=8000] - Timeout in milliseconds for remote README fetch during build
+ * @param {boolean} [config.homePage.fallbackToLocal=true] - Fallback to local Homepage.{lang}.md when remote fetch fails
  * @returns {Object} Resolved Docsector configuration
  */
 export function createDocsector (config = {}) {
@@ -217,6 +222,14 @@ export function createDocsector (config = {}) {
         copyCurrentPage: true,
         ...(config.webMcp?.tools || {})
       }
+    },
+
+    homePage: {
+      source: 'local',
+      remoteReadmeUrl: null,
+      timeoutMs: 8000,
+      fallbackToLocal: true,
+      ...config.homePage
     }
   }
 }

package/src/quasar.factory.js

@@ -141,7 +141,6 @@ function createPrerenderMetaPlugin (projectRoot) {
     async closeBundle () {
       const distDir = resolve(projectRoot, 'dist', 'spa')
       const baseHtmlPath = resolve(distDir, 'index.html')
-
       if (!existsSync(baseHtmlPath)) return
 
       const baseHtml = readFileSync(baseHtmlPath, 'utf-8')
@@ -421,6 +420,148 @@ function createGitDatesPlugin (projectRoot) {
   }
 }
 
+function getHomePageConfig (config = {}) {
+  const homePage = config.homePage || {}
+  return {
+    source: homePage.source || 'local',
+    remoteReadmeUrl: homePage.remoteReadmeUrl || null,
+    timeoutMs: Number.isFinite(homePage.timeoutMs)
+      ? Math.max(1000, Number(homePage.timeoutMs))
+      : 8000,
+    fallbackToLocal: homePage.fallbackToLocal !== false
+  }
+}
+
+function getConfiguredLanguages (config = {}) {
+  const defaultLang = config.defaultLanguage || config.languages?.[0]?.value || 'en-US'
+  const languageValues = config.languages?.map(language => language.value).filter(Boolean) || []
+  const langs = [...new Set([defaultLang, ...languageValues])]
+  return { defaultLang, langs }
+}
+
+async function fetchRemoteMarkdown (url, timeoutMs = 8000) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), timeoutMs)
+
+  try {
+    const response = await fetch(url, {
+      headers: {
+        Accept: 'text/markdown, text/plain;q=0.9, */*;q=0.8'
+      },
+      signal: controller.signal
+    })
+
+    if (!response.ok) {
+      throw new Error(`Remote README request failed with status ${response.status}`)
+    }
+
+    return await response.text()
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+async function resolveHomePageSources (projectRoot, config = {}, options = {}) {
+  const { logPrefix = '[docsector]' } = options
+  const pagesDir = resolve(projectRoot, 'src', 'pages')
+  const { defaultLang, langs } = getConfiguredLanguages(config)
+  const homePageConfig = getHomePageConfig(config)
+
+  const byLang = {}
+  let mode = 'local'
+
+  if (homePageConfig.source === 'remote-readme' && homePageConfig.remoteReadmeUrl) {
+    try {
+      const remote = await fetchRemoteMarkdown(homePageConfig.remoteReadmeUrl, homePageConfig.timeoutMs)
+      for (const lang of langs) {
+        byLang[lang] = remote
+      }
+      mode = 'remote-readme'
+      console.log(`\x1b[36m${logPrefix}\x1b[0m Loaded remote README for home page`)
+      return { mode, byLang, defaultLang, langs }
+    } catch (error) {
+      const reason = error?.message || String(error)
+      console.warn(`${logPrefix} Failed to load remote README for home page: ${reason}`)
+
+      if (!homePageConfig.fallbackToLocal) {
+        throw error
+      }
+    }
+  }
+
+  for (const lang of langs) {
+    const homepage = resolve(pagesDir, `Homepage.${lang}.md`)
+    if (existsSync(homepage)) {
+      byLang[lang] = readFileSync(homepage, 'utf-8')
+      continue
+    }
+
+    const fallback = resolve(pagesDir, `Homepage.${defaultLang}.md`)
+    if (existsSync(fallback)) {
+      byLang[lang] = readFileSync(fallback, 'utf-8')
+    }
+  }
+
+  return { mode, byLang, defaultLang, langs }
+}
+
+function createHomePageOverridePlugin (projectRoot) {
+  const virtualId = 'virtual:docsector-homepage-override'
+  const resolvedId = '\0' + virtualId
+  let byLang = null
+  let loadPromise = null
+
+  const ensureSources = async () => {
+    if (byLang) return byLang
+    if (!loadPromise) {
+      loadPromise = (async () => {
+        const configUrl = pathToFileURL(resolve(projectRoot, 'docsector.config.js')).href
+        const { default: config } = await import(configUrl)
+        const sources = await resolveHomePageSources(projectRoot, config, { logPrefix: '[docsector]' })
+        byLang = sources.byLang
+        return byLang
+      })().finally(() => {
+        loadPromise = null
+      })
+    }
+
+    return loadPromise
+  }
+
+  return {
+    name: 'docsector-homepage-override',
+    resolveId (id) {
+      if (id === virtualId) return resolvedId
+    },
+    async buildStart () {
+      await ensureSources()
+    },
+    configureServer () {
+      ensureSources().catch((error) => {
+        console.warn(`[docsector] Could not prepare home page override: ${error?.message || String(error)}`)
+      })
+    },
+    async load (id) {
+      if (id === resolvedId) {
+        await ensureSources()
+        return `export default ${JSON.stringify(byLang || {})}`
+      }
+
+      await ensureSources()
+      if (!byLang) return null
+
+      const match = id.match(/Homepage\.([A-Za-z0-9-]+)\.md\?raw(?:$|&)/)
+      if (!match) return null
+
+      const lang = match[1]
+      const content = byLang[lang]
+      if (typeof content !== 'string') return null
+
+      return `export default ${JSON.stringify(content)}`
+    }
+  }
+}
+
 /**
  * Create a Vite plugin that serves raw Markdown content for `.md` suffixed URLs.
  *
@@ -496,32 +637,63 @@ function createMarkdownEndpointPlugin (projectRoot) {
     name: 'docsector-markdown-endpoint',
 
     configureServer (server) {
-      // Read default language from config
       let defaultLang = 'en-US'
       let markdownNegotiationEnabled = true
       let markdownAgentFallback = true
-      try {
-        const configPath = resolve(projectRoot, 'docsector.config.js')
-        if (existsSync(configPath)) {
-          // Dynamic import in dev — we read it synchronously via a simple approach
-          const configContent = readFileSync(configPath, 'utf-8')
-          const match = configContent.match(/defaultLanguage\s*:\s*['"]([^'"]+)['"]/)
-          if (match) defaultLang = match[1]
-
-          const enabledMatch = configContent.match(/markdownNegotiation\s*:\s*\{[\s\S]*?enabled\s*:\s*(true|false)/)
-          if (enabledMatch) markdownNegotiationEnabled = enabledMatch[1] === 'true'
-
-          const fallbackMatch = configContent.match(/markdownNegotiation\s*:\s*\{[\s\S]*?agentFallback\s*:\s*(true|false)/)
-          if (fallbackMatch) markdownAgentFallback = fallbackMatch[1] === 'true'
+      let homepageByLang = null
+
+      const configReady = (async () => {
+        try {
+          const configUrl = pathToFileURL(resolve(projectRoot, 'docsector.config.js')).href
+          const { default: config } = await import(configUrl)
+
+          defaultLang = config.defaultLanguage || config.languages?.[0]?.value || 'en-US'
+          const markdownNegotiationConfig = config.markdownNegotiation || {}
+          markdownNegotiationEnabled = markdownNegotiationConfig.enabled !== false
+          markdownAgentFallback = markdownNegotiationConfig.agentFallback !== false
+
+          const sources = await resolveHomePageSources(projectRoot, config, { logPrefix: '[docsector]' })
+          homepageByLang = sources.byLang
+        } catch (error) {
+          console.warn(`[docsector] Could not load config for markdown endpoint: ${error?.message || String(error)}`)
         }
-      } catch { /* use fallback */ }
+      })()
+
+      server.middlewares.use(async (req, res, next) => {
+        await configReady
 
-      server.middlewares.use((req, res, next) => {
         const url = new URL(req.url, 'http://localhost')
         const accept = (req.headers.accept || '').toLowerCase()
         const wantsMarkdown = accept.includes('text/markdown')
         const lang = url.searchParams.get('lang') || defaultLang
 
+        const homepagePath = url.pathname === '/' || url.pathname === '/index.html'
+        const remoteHomepage = homepageByLang?.[lang] || homepageByLang?.[defaultLang] || null
+
+        const homepageMarkdownMatch = url.pathname.match(/^\/homepage(?:\.([A-Za-z0-9-]+))?\.md$/i)
+        if (homepageMarkdownMatch) {
+          const requestedLang = homepageMarkdownMatch[1] || lang
+          const homepageMarkdown = homepageByLang?.[requestedLang] || homepageByLang?.[defaultLang] || null
+
+          if (typeof homepageMarkdown === 'string' && homepageMarkdown.length > 0) {
+            res.setHeader('Content-Type', 'text/markdown; charset=utf-8')
+            res.setHeader('Vary', 'Accept')
+            res.setHeader('x-markdown-tokens', String(estimateMarkdownTokens(homepageMarkdown)))
+            res.end(homepageMarkdown)
+            return
+          }
+        }
+
+        if (homepagePath && typeof remoteHomepage === 'string' && remoteHomepage.length > 0) {
+          if ((markdownNegotiationEnabled && wantsMarkdown) || (markdownAgentFallback && LLM_BOT_PATTERN.test(req.headers['user-agent'] || ''))) {
+            res.setHeader('Content-Type', 'text/markdown; charset=utf-8')
+            res.setHeader('Vary', 'Accept')
+            res.setHeader('x-markdown-tokens', String(estimateMarkdownTokens(remoteHomepage)))
+            res.end(remoteHomepage)
+            return
+          }
+        }
+
         // Explicit .md request
         if (url.pathname.endsWith('.md')) {
           const file = resolveMarkdownFile(url.pathname, lang)
@@ -620,16 +792,14 @@ function createMarkdownBuildPlugin (projectRoot) {
       }
 
       // Generate homepage markdown files so root content can be negotiated in production
-      const languageValues = config.languages?.map(language => language.value).filter(Boolean) || []
-      const allLangs = [...new Set([defaultLang, ...languageValues])]
+      const homepageSources = await resolveHomePageSources(projectRoot, config, { logPrefix: '[docsector]' })
       let homepageCount = 0
-      for (const lang of allLangs) {
-        const homepageSrc = resolve(pagesDir, `Homepage.${lang}.md`)
-        if (!existsSync(homepageSrc)) continue
+      for (const lang of homepageSources.langs) {
+        const homepageContent = homepageSources.byLang?.[lang]
+        if (typeof homepageContent !== 'string' || homepageContent.length === 0) continue
 
-        const homepageContent = readFileSync(homepageSrc, 'utf-8')
         writeFileSync(resolve(distDir, `homepage.${lang}.md`), homepageContent)
-        if (lang === defaultLang) {
+        if (lang === homepageSources.defaultLang) {
           writeFileSync(resolve(distDir, 'homepage.md'), homepageContent)
         }
         homepageCount++
@@ -1705,6 +1875,7 @@ export function createQuasarConfig (options = {}) {
 
       vitePlugins: [
         createHjsonPlugin(),
+        createHomePageOverridePlugin(projectRoot),
         createGitDatesPlugin(projectRoot),
         createMarkdownEndpointPlugin(projectRoot),
         createMarkdownBuildPlugin(projectRoot),