@docsector/docsector-reader 3.6.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
@@ -64,17 +64,16 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 📅 **Last Updated Date** — Automatic per-page "last updated" date from git commit history, locale-formatted
 - 📊 **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 Negotiation** — Responds with Markdown when clients send `Accept: text/markdown`, while keeping HTML as browser default
-- 🔐 **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
+- 🌍 **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-expandable title="...">...</d-expandable>` to collapse secondary content while keeping rich Markdown support inside the body
-- 📎 **File Attachment Blocks** — Use `<d-file src="/files/...">...</d-file>` in Markdown to render downloadable file cards with automatic local size detection and support for external URLs
-- 🌐 **Embedded URL Blocks** — Use `<d-embedded-url url="https://...">...</d-embedded-url>` to render curated embeds for YouTube, Vimeo, Spotify, and CodePen with a safe link-card fallback for unsupported URLs
-- 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
+- 📖 **Expandable Markdown Sections** — Use `<d-block-expandable title="...">...</d-block-expandable>` to collapse secondary content while keeping rich Markdown support inside the body
+- 1️⃣ **Stepper Guides** — Use `<d-block-stepper>` with nested `<d-block-step title="...">...</d-block-step>` items to render native Quasar vertical steppers with rich Markdown and optional per-step icon overrides
+- 🕒 **Timeline Updates** — Use `<d-block-timeline>` with nested `<d-block-timeline-item date="...">...</d-block-timeline-item>` entries and optional `<d-block-timeline-tag>` labels to publish GitBook-inspired changelog items with direct-link anchors, tag icons/colors, and rich Markdown bodies
+- 📎 **File Attachment Blocks** — Use `<d-block-file src="/files/...">...</d-block-file>` in Markdown to render downloadable file cards with automatic local size detection and support for external URLs
+- 🌐 **Embedded URL Blocks** — Use `<d-block-embedded-url url="https://...">...</d-block-embedded-url>` to render curated embeds for YouTube, Vimeo, Spotify, and CodePen with a safe link-card fallback for unsupported URLs
+- 🧭 **Quick Links Custom Element** — Use `<d-block-quick-links>` and `<d-block-quick-link>` in Markdown to render rich home navigation cards
 - 🗂️ **Cards Custom Element** — Use `<d-block-cards>` and `<d-block-card>` in Markdown to render linked content cards with optional cover images
 - 🗂️ **API Catalog Well-Known** — Auto-generates `/.well-known/api-catalog` as Linkset JSON for machine-readable API discovery
 - 🗃️ **Multi-Version History** — Archive older major versions under `src/pages/.old/<version>/` and expose them at prefixed routes (e.g. `/v0.x/guide/...`) while keeping the current docs at unprefixed routes
@@ -361,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
@@ -1026,9 +1026,9 @@ Regular blockquotes without `[!TYPE]` continue to work normally.
 ### File Attachment Blocks
 
 ```html
-<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+<d-block-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
 Download the example file bundled with the docs.
-</d-file>
+</d-block-file>
 ```
 
 Notes:
@@ -1041,9 +1041,9 @@ Notes:
 ### Embedded URL Blocks
 
 ```html
-<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube player demo">
+<d-block-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube player demo">
 Optional caption rendered as inline Markdown.
-</d-embedded-url>
+</d-block-embedded-url>
 ```
 
 Notes:

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '3.6.0'
+const VERSION = '4.0.1'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -488,288 +488,6 @@ Docsector Reader is a markdown-first documentation engine.
 - Repository: [docsector/docsector-reader](https://github.com/docsector/docsector-reader)
 `
 
-const TEMPLATE_BOOT_PAGE = `\
-<template>
-<q-page-container>
-  <q-page class="boot-page">
-    <!-- Hero Section -->
-    <div class="hero-section">
-      <div class="hero-content">
-        <div class="hero-icon-container">
-          <q-icon name="auto_stories" size="64px" color="white" />
-        </div>
-        <h1 class="hero-title">{{ projectName }}</h1>
-        <p class="hero-subtitle">{{ $t('_.home.texts[0]') }}{{ projectName }}</p>
-        <p class="hero-description">{{ $t('_.home.texts[2]') }}</p>
-        <div class="hero-actions">
-          <q-btn
-            unelevated
-            color="white"
-            text-color="primary"
-            label="Get Started"
-            icon="rocket_launch"
-            to="/guide/getting-started/overview"
-            class="hero-btn"
-            size="lg"
-            no-caps
-          />
-          <q-btn
-            v-if="projectUrl !== '#'"
-            outline
-            color="white"
-            label="GitHub"
-            icon="fab fa-github"
-            @click="openURL(projectUrl)"
-            class="hero-btn"
-            size="lg"
-            no-caps
-          />
-        </div>
-      </div>
-    </div>
-
-    <!-- Features Section -->
-    <div class="features-section">
-      <div class="features-grid">
-        <div class="feature-card">
-          <q-icon name="edit_note" size="40px" color="primary" />
-          <h3>Markdown Powered</h3>
-          <p>Write your documentation in Markdown. Pages are automatically converted into beautiful, navigable content.</p>
-        </div>
-        <div class="feature-card">
-          <q-icon name="translate" size="40px" color="primary" />
-          <h3>Multi-language</h3>
-          <p>Built-in i18n support. Add translations by creating locale files — no extra configuration needed.</p>
-        </div>
-        <div class="feature-card">
-          <q-icon name="palette" size="40px" color="primary" />
-          <h3>Beautiful UI</h3>
-          <p>Powered by Quasar Framework. Responsive, accessible, and production-ready out of the box.</p>
-        </div>
-        <div class="feature-card">
-          <q-icon name="bolt" size="40px" color="primary" />
-          <h3>Lightning Fast</h3>
-          <p>Vite-powered dev server with hot-reload. See your changes instantly as you write.</p>
-        </div>
-        <div class="feature-card">
-          <q-icon name="search" size="40px" color="primary" />
-          <h3>Full-text Search</h3>
-          <p>Instant client-side search across all your documentation pages and translations.</p>
-        </div>
-        <div class="feature-card">
-          <q-icon name="settings" size="40px" color="primary" />
-          <h3>Easy Configuration</h3>
-          <p>One config file for branding, links, languages, and GitHub integration.</p>
-        </div>
-      </div>
-    </div>
-
-    <!-- Quick Start Section -->
-    <div class="quickstart-section">
-      <h2 class="section-title">Quick Links</h2>
-      <div class="quickstart-grid">
-        <q-card flat bordered class="quickstart-card" clickable @click="$router.push('/guide/getting-started/overview')">
-          <q-card-section horizontal>
-            <q-card-section class="flex flex-center" style="width: 60px;">
-              <q-icon name="flag" size="28px" color="primary" />
-            </q-card-section>
-            <q-card-section>
-              <div class="text-subtitle1 text-weight-bold">Getting Started</div>
-              <div class="text-caption text-grey-7">Installation, setup, and your first page</div>
-            </q-card-section>
-            <q-space />
-            <q-card-section class="flex flex-center">
-              <q-icon name="chevron_right" color="grey-5" />
-            </q-card-section>
-          </q-card-section>
-        </q-card>
-      </div>
-    </div>
-
-    <!-- Footer -->
-    <div class="boot-footer">
-      <p>{{ $t('_.home.texts[1]') }}
-        <a :href="projectUrl" target="_blank" class="footer-link">Docsector Reader</a>
-      </p>
-    </div>
-  </q-page>
-</q-page-container>
-</template>
-
-<script setup>
-import { openURL } from 'quasar'
-import docsectorConfig from 'docsector.config.js'
-
-defineOptions({ name: 'BootPage' })
-
-const projectName = docsectorConfig.branding?.name || 'My Documentation'
-const projectUrl = docsectorConfig.links?.github || '#'
-</script>
-
-<style lang="sass" scoped>
-.boot-page
-  padding: 0 !important
-
-// Hero
-.hero-section
-  background: linear-gradient(135deg, #655529 0%, #8b7340 50%, #a08850 100%)
-  color: white
-  padding: 80px 24px 60px
-  text-align: center
-  position: relative
-  overflow: hidden
-
-  &::before
-    content: ''
-    position: absolute
-    top: -50%
-    left: -50%
-    width: 200%
-    height: 200%
-    background: radial-gradient(circle, rgba(255,255,255,0.05) 0%, transparent 60%)
-    animation: pulse 8s ease-in-out infinite
-
-@keyframes pulse
-  0%, 100%
-    transform: scale(1)
-  50%
-    transform: scale(1.1)
-
-.hero-content
-  position: relative
-  z-index: 1
-  max-width: 700px
-  margin: 0 auto
-
-.hero-icon-container
-  margin-bottom: 24px
-  .q-icon
-    opacity: 0.9
-
-.hero-title
-  font-size: 2.8rem
-  font-weight: 700
-  margin: 0 0 12px
-  line-height: 1.2
-  letter-spacing: -0.02em
-
-.hero-subtitle
-  font-size: 1.2rem
-  opacity: 0.9
-  margin: 0 0 8px
-  font-weight: 400
-
-.hero-description
-  font-size: 1rem
-  opacity: 0.7
-  margin: 0 0 32px
-
-.hero-actions
-  display: flex
-  gap: 16px
-  justify-content: center
-  flex-wrap: wrap
-
-.hero-btn
-  border-radius: 8px
-  padding: 8px 28px
-  font-weight: 600
-
-// Features
-.features-section
-  padding: 60px 24px
-  max-width: 1100px
-  margin: 0 auto
-
-.features-grid
-  display: grid
-  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))
-  gap: 24px
-
-.feature-card
-  padding: 28px 24px
-  border-radius: 12px
-  border: 1px solid #e8e8e8
-  transition: transform 0.2s, box-shadow 0.2s
-  text-align: center
-
-  &:hover
-    transform: translateY(-4px)
-    box-shadow: 0 8px 25px rgba(0,0,0,0.08)
-
-  h3
-    font-size: 1.1rem
-    font-weight: 600
-    margin: 16px 0 8px
-    color: #333
-
-  p
-    font-size: 0.9rem
-    color: #666
-    line-height: 1.5
-    margin: 0
-
-// Quick Start
-.quickstart-section
-  padding: 40px 24px 60px
-  max-width: 700px
-  margin: 0 auto
-
-.section-title
-  font-size: 1.6rem
-  font-weight: 700
-  text-align: center
-  margin: 0 0 24px
-  color: #333
-
-.quickstart-grid
-  display: flex
-  flex-direction: column
-  gap: 12px
-
-.quickstart-card
-  border-radius: 10px
-  transition: box-shadow 0.2s
-  cursor: pointer
-
-  &:hover
-    box-shadow: 0 4px 15px rgba(0,0,0,0.1)
-
-// Footer
-.boot-footer
-  text-align: center
-  padding: 24px
-  border-top: 1px solid #e8e8e8
-  color: #999
-  font-size: 0.85rem
-
-  .footer-link
-    color: #655529
-    text-decoration: none
-    font-weight: 500
-
-    &:hover
-      text-decoration: underline
-
-// Dark mode
-body.body--dark
-  .feature-card
-    border-color: #333
-    h3
-      color: #e0e0e0
-    p
-      color: #aaa
-
-  .section-title
-    color: #e0e0e0
-
-  .boot-footer
-    border-color: #333
-    .footer-link
-      color: #c4a856
-</style>
-`
-
 const TEMPLATE_404_PAGE = `\
 <template>
 <q-page-container>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.6.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/{DPageBlockquote.vue → DBlockBlockquote.vue}

@@ -2,6 +2,10 @@
 // defineProps is a compiler macro in <script setup>, no import needed
 import { computed } from 'vue'
 
+defineOptions({
+  name: 'DBlockBlockquote'
+})
+
 const props = defineProps({
   message: {
     type: String,

package/src/components/{DBlockCard.vue → DBlockCards.vue}

@@ -2,7 +2,7 @@
 const BASE_URL = import.meta.env.BASE_URL || '/'
 
 defineOptions({
-  name: 'DBlockCard'
+  name: 'DBlockCards'
 })
 
 const props = defineProps({

package/src/components/{DPageEmbeddedUrl.vue → DBlockEmbeddedUrl.vue}

@@ -5,7 +5,7 @@ import { useI18n } from 'vue-i18n'
 import { resolveEmbeddedUrl } from '../composables/useEmbeddedUrl'
 
 defineOptions({
-  name: 'DPageEmbeddedUrl'
+  name: 'DBlockEmbeddedUrl'
 })
 
 const props = defineProps({

package/src/components/{DPageExpandable.vue → DBlockExpandable.vue}

@@ -1,4 +1,8 @@
 <script setup>
+defineOptions({
+  name: 'DBlockExpandable'
+})
+
 defineProps({
   title: {
     type: String,
@@ -55,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/{DPageFile.vue → DBlockFile.vue}

@@ -8,7 +8,7 @@ import { resolveFileIconUrl } from '../composables/useFileIcon'
 const BASE_URL = import.meta.env.BASE_URL || '/'
 
 defineOptions({
-  name: 'DPageFile'
+  name: 'DBlockFile'
 })
 
 const props = defineProps({

package/src/components/{DPageImage.vue → DBlockImage.vue}

@@ -2,7 +2,7 @@
 import { computed } from 'vue'
 
 defineOptions({
-  name: 'DPageImage'
+  name: 'DBlockImage'
 })
 
 const props = defineProps({

package/src/components/{DMermaidDiagram.vue → DBlockMermaidDiagram.vue}

@@ -2,6 +2,10 @@
 import { ref, onMounted, watch } from 'vue'
 import { useQuasar } from 'quasar'
 
+defineOptions({
+  name: 'DBlockMermaidDiagram'
+})
+
 const props = defineProps({
   content: {
     type: String,

package/src/components/{DQuickLinks.vue → DBlockQuickLinks.vue}

@@ -1,4 +1,8 @@
 <script setup>
+defineOptions({
+  name: 'DBlockQuickLinks'
+})
+
 const props = defineProps({
   items: {
     type: Array,

package/src/components/{DPageSourceCode.vue → DBlockSourceCode.vue}

@@ -11,6 +11,10 @@ import 'prismjs/components/prism-php'
 import 'prismjs/components/prism-bash'
 import { looksLikeFileName, resolveFileIconUrl } from '../composables/useFileIcon'
 
+defineOptions({
+  name: 'DBlockSourceCode'
+})
+
 const props = defineProps({
   index: {
     type: Number,
@@ -504,11 +508,12 @@ function printToLetter(number) {
     padding: 0
 
     .lines
-      padding: 11px 5px 8px 5px
+      padding: 10px 5px 10px 5px
       text-align: right
       float: left
       -webkit-user-select: none
       user-select: none
+      line-height: 19px
 
       a
         display: block