@docsector/docsector-reader 4.0.0 → 4.0.1

package/README.md

@@ -3,7 +3,7 @@
 </p>
 <h1 align="center">Docsector Reader 📖</h1>
 <p align="center">
-  <i>A documentation rendering engine built with Vue 3, Quasar v2 and Vite.</i>
+  <i>A documentation rendering engine built with Vue 3, Quasar v2 and Vite with AI features.</i>
 </p>
 <p align="center">
   <a href="https://www.npmjs.com/package/@docsector/docsector-reader">
@@ -50,7 +50,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🚨 **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
 - 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin
-- 🔗 **Anchor Navigation** — Right-side Table of Contents tree with scroll tracking and auto-scroll to active section
+- 🔗 **Anchor Navigation** — Right-side Table of Contents tree with stable scroll tracking, auto-scroll to the active section, and active-heading resolution based on the last heading that crossed the content threshold
 - 🖱️ **Active Menu Item UX** — Active menu entries keep pointer cursor, clear URL hash without redundant navigation, and prevent accidental label text selection
 - 🔎 **Search** — Menu search across all documentation content and tags
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers
@@ -65,7 +65,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📊 **Translation Progress** — Automatic translation percentage based on header coverage
 - 🌐 **Accurate Available Translations** — Locale availability counter now uses actual localized page source presence, avoiding false negatives when metadata is equal
 - 🏠 **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
+- 🌍 **Remote README as Home** — Optional build-time remote README source for homepage with automatic local fallback and automatic primary-title handoff when the remote README already provides the project heading
 - 🔗 **GitHub-Compatible Heading Anchors** — Markdown headings use GitHub-style slugs so standard README Table of Contents links work inside Docsector
 - 🧬 **Scaffolded Homepage Override Wiring** — New consumer projects automatically wire `virtual:docsector-homepage-override` into i18n message building
 - 📖 **Expandable Markdown Sections** — Use `<d-block-expandable title="...">...</d-block-expandable>` to collapse secondary content while keeping rich Markdown support inside the body
@@ -360,7 +360,8 @@ 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.
+- When the remote README resolves successfully, Docsector hides the autogenerated homepage title and uses the README's own primary heading in the rendered content.
+- If fetch fails, it falls back to local `src/pages/Homepage.{lang}.md` by default and keeps the usual autogenerated homepage title.
 - Standard GitHub-style heading links and README Table of Contents fragments keep working in the rendered homepage.
 
 ### Configure

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '4.0.0'
+const VERSION = '4.0.1'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "4.0.0",
+  "version": "4.0.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/DBlockExpandable.vue

@@ -59,6 +59,7 @@ body.body--dark
   .q-item
     min-height: 0
     padding: 0
+    height: 35px
 
   .q-item__section--side
     padding-left: 0.55rem

package/src/components/DPageSection.vue

@@ -11,6 +11,10 @@ defineProps({
   id: {
     type: Number,
     required: true
+  },
+  renderPrimaryHeading: {
+    type: Boolean,
+    default: false
   }
 })
 
@@ -32,6 +36,7 @@ const tokenized = computed(() => {
 <section>
   <d-page-tokens
     :id="id"
+    :render-primary-heading="renderPrimaryHeading"
     :tokens="tokenized"
   />
 </section>

package/src/components/DPageTokens.vue

@@ -8,6 +8,10 @@ defineProps({
     type: Number,
     default: 0
   },
+  renderPrimaryHeading: {
+    type: Boolean,
+    default: false
+  },
   tokens: {
     type: Array,
     default: () => []
@@ -34,8 +38,13 @@ import DBlockStepper from './DBlockStepper.vue'
 
 <template>
 <template v-for="(token, index) in tokens" :key="`${token.tag}-${index}`">
+  <h1
+    v-if="token.tag === 'h1' && renderPrimaryHeading"
+    :id="token.anchorId"
+    v-html="token.content"
+  ></h1>
   <d-h2
-    v-if="token.tag === 'h2'"
+    v-else-if="token.tag === 'h2'"
     :id="token.anchorId"
     :value="token.content"
   />

package/src/components/DSubpage.vue

@@ -1,13 +1,17 @@
 <script setup>
 import { computed } from 'vue'
 import { useRoute } from 'vue-router'
+import { useStore } from 'vuex'
+import { homePageSourceMode } from 'virtual:docsector-homepage-override'
 // components
 import DPage from "./DPage.vue";
 import DPageBar from "./DPageBar.vue";
 import DH1 from "./DH1.vue";
 import DPageSection from "./DPageSection.vue";
+import { usesRemoteReadmeHomeContent } from '../home-page-mode'
 
 const route = useRoute()
+const store = useStore()
 
 const id = computed(() => {
   const path = route.path
@@ -19,6 +23,13 @@ const id = computed(() => {
 
   return hash >>> 0
 })
+
+const usesRemoteReadmeHome = computed(() => {
+  return usesRemoteReadmeHomeContent({
+    pageBase: store.state.page.base,
+    homePageSourceMode
+  })
+})
 </script>
 
 <template>
@@ -26,11 +37,12 @@ const id = computed(() => {
   <header>
     <d-page-bar />
     <hr />
-    <d-h1 :id="0" />
+    <d-h1 v-if="!usesRemoteReadmeHome" :id="0" />
+    <span v-else id="0" aria-hidden="true"></span>
   </header>
 
   <main>
-    <d-page-section :id="id" />
+    <d-page-section :id="id" :render-primary-heading="usesRemoteReadmeHome" />
   </main>
 </d-page>
 </template>

package/src/composables/useActiveAnchor.js

@@ -0,0 +1,42 @@
+export const DEFAULT_ACTIVE_ANCHOR_OFFSET = 50
+
+const toFiniteNumber = (value) => {
+  const normalized = Number(value)
+  return Number.isFinite(normalized) ? normalized : 0
+}
+
+export function getActiveAnchorId({
+  anchors = [],
+  scrollTop = 0,
+  scrollOffset = DEFAULT_ACTIVE_ANCHOR_OFFSET,
+  rootAnchorId = 0,
+  getAnchorOffsetTop = () => undefined
+} = {}) {
+  const thresholdTop = Math.max(0, toFiniteNumber(scrollTop)) + Math.max(0, toFiniteNumber(scrollOffset))
+  let activeAnchorId = rootAnchorId
+  const seenAnchors = new Set()
+
+  for (const anchorId of Array.isArray(anchors) ? anchors : []) {
+    if (anchorId === null || anchorId === undefined || anchorId === false || anchorId === 0 || anchorId === '0') {
+      continue
+    }
+
+    if (seenAnchors.has(anchorId)) {
+      continue
+    }
+
+    seenAnchors.add(anchorId)
+
+    const resolvedOffsetTop = Number(getAnchorOffsetTop(anchorId))
+
+    if (!Number.isFinite(resolvedOffsetTop)) {
+      continue
+    }
+
+    if (thresholdTop >= resolvedOffsetTop) {
+      activeAnchorId = anchorId
+    }
+  }
+
+  return activeAnchorId
+}

package/src/composables/useNavigator.js

@@ -3,6 +3,8 @@ import { useStore } from 'vuex'
 import { useRouter, useRoute } from 'vue-router'
 import { ref } from 'vue'
 
+import { DEFAULT_ACTIVE_ANCHOR_OFFSET, getActiveAnchorId } from './useActiveAnchor'
+
 export default function useNavigator() {
   const store = useStore()
   const router = useRouter()
@@ -46,7 +48,10 @@ export default function useNavigator() {
   const select = (id) => {
     const normalized = normalizeStoreAnchorId(id)
 
-    store.commit('page/setAnchor', normalized)
+    if (store.state.page.anchor !== normalized) {
+      store.commit('page/setAnchor', normalized)
+    }
+
     store.commit('page/pushNodesExpanded', normalized)
   }
 
@@ -78,27 +83,29 @@ export default function useNavigator() {
       return
     }
 
-    const scrollPositionTop = scroll.position.top + 50
-    const anchors = store.state.page.anchors
+    const activeAnchorId = getActiveAnchorId({
+      anchors: store.state.page.anchors,
+      scrollTop: scroll?.position?.top,
+      scrollOffset: DEFAULT_ACTIVE_ANCHOR_OFFSET,
+      rootAnchorId: 0,
+      getAnchorOffsetTop: (anchorId) => {
+        const domAnchorId = normalizeDomAnchorId(anchorId)
 
-    for (let i = 0; i < anchors.length; i++) {
-      const anchorId = anchors[i]
-      const domAnchorId = normalizeDomAnchorId(anchorId)
+        if (domAnchorId === '') {
+          return undefined
+        }
 
-      if (domAnchorId === '0') {
-        continue
-      }
+        const Anchor = document.getElementById(domAnchorId)
 
-      const Anchor = document.getElementById(domAnchorId)
-      let AnchorOffsetTop = 20
-      if (Anchor !== null && typeof Anchor === 'object') {
-        AnchorOffsetTop = Anchor.offsetTop
-      }
+        if (Anchor !== null && typeof Anchor === 'object') {
+          return Anchor.offsetTop
+        }
 
-      if (scrollPositionTop >= AnchorOffsetTop) {
-        select(anchorId)
+        return undefined
       }
-    }
+    })
+
+    select(activeAnchorId)
   }
 
   const navigate = (value, toAnchor = true) => {

package/src/home-page-mode.js

@@ -0,0 +1,5 @@
+export const REMOTE_README_HOME_PAGE_MODE = 'remote-readme'
+
+export function usesRemoteReadmeHomeContent ({ pageBase = '', homePageSourceMode = 'local' } = {}) {
+  return pageBase === 'home' && homePageSourceMode === REMOTE_README_HOME_PAGE_MODE
+}

package/src/pages/manual/basic/d-page-anchor.overview.en-US.md

@@ -39,7 +39,7 @@ The root node (from DH1) shows the page title from i18n when no label is set:
 
 ## Scroll Synchronization
 
-When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which iterates over registered anchors and selects the one closest to the current scroll position. This keeps the table of contents in sync with the visible content.
+When the user scrolls the page content, the `DPage` scroll observer calls `useNavigator().scrolling()`, which selects the last registered heading that crossed the content threshold. Missing or stale anchors are ignored so the table of contents stays in sync with the visible section instead of jumping ahead.
 
 ## Lifecycle
 

package/src/pages/manual/basic/d-page-anchor.overview.pt-BR.md

@@ -39,7 +39,7 @@ O nó raiz (do DH1) mostra o título da página do i18n quando nenhum label é d
 
 ## Sincronização de Scroll
 
-Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que itera sobre as âncoras registradas e seleciona a mais próxima da posição de scroll atual. Isso mantém o índice sincronizado com o conteúdo visível.
+Quando o usuário faz scroll no conteúdo da página, o observador de scroll do `DPage` chama `useNavigator().scrolling()`, que seleciona o último heading registrado que cruzou o limite superior da área de conteúdo. Âncoras ausentes ou obsoletas são ignoradas para manter o índice sincronizado com a seção realmente visível, sem saltar adiante.
 
 ## Ciclo de Vida
 

package/src/quasar.factory.js

@@ -1504,7 +1504,7 @@ async function fetchRemoteMarkdown (url, timeoutMs = 8000) {
   }
 }
 
-async function resolveHomePageSources (projectRoot, config = {}, options = {}) {
+export async function resolveHomePageSources (projectRoot, config = {}, options = {}) {
   const { logPrefix = '[docsector]' } = options
   const pagesDir = resolve(projectRoot, 'src', 'pages')
   const { defaultLang, langs } = getConfiguredLanguages(config)
@@ -1551,18 +1551,17 @@ async function resolveHomePageSources (projectRoot, config = {}, options = {}) {
 function createHomePageOverridePlugin (projectRoot) {
   const virtualId = 'virtual:docsector-homepage-override'
   const resolvedId = '\0' + virtualId
-  let byLang = null
+  let homePageSources = null
   let loadPromise = null
 
   const ensureSources = async () => {
-    if (byLang) return byLang
+    if (homePageSources) return homePageSources
     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
+        homePageSources = await resolveHomePageSources(projectRoot, config, { logPrefix: '[docsector]' })
+        return homePageSources
       })().finally(() => {
         loadPromise = null
       })
@@ -1586,18 +1585,21 @@ function createHomePageOverridePlugin (projectRoot) {
     },
     async load (id) {
       if (id === resolvedId) {
-        await ensureSources()
-        return `export default ${JSON.stringify(byLang || {})}`
+        const sources = await ensureSources()
+        return [
+          `export const homePageSourceMode = ${JSON.stringify(sources?.mode || 'local')}`,
+          `export default ${JSON.stringify(sources?.byLang || {})}`
+        ].join('\n')
       }
 
-      await ensureSources()
-      if (!byLang) return null
+      const sources = await ensureSources()
+      if (!sources?.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]
+      const content = sources.byLang[lang]
       if (typeof content !== 'string') return null
 
       return `export default ${JSON.stringify(content)}`

package/src/store/Page.js

@@ -46,7 +46,7 @@ export default {
     pushAnchors (state, value) {
       if (value === false) {
         state.anchors = []
-      } else {
+      } else if (!state.anchors.includes(value)) {
         // index: id
         state.anchors.push(value)
       }
@@ -82,7 +82,9 @@ export default {
       state.nodesExpanded = [0]
     },
     pushNodesExpanded (state, nodeId) {
-      state.nodesExpanded.push(nodeId)
+      if (!state.nodesExpanded.includes(nodeId)) {
+        state.nodesExpanded.push(nodeId)
+      }
     },
 
     setScrolling (state, val) {