@docsector/docsector-reader 3.6.0 → 4.0.0

package/README.md

@@ -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
 - 🔗 **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
@@ -1026,9 +1025,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 +1040,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.0'
 
 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.0",
   "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,

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

package/src/components/DBlockStepper.vue

@@ -0,0 +1,210 @@
+<script setup>
+import { computed, ref, watch } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+defineOptions({
+  name: 'DBlockStepper'
+})
+
+const props = defineProps({
+  steps: {
+    type: Array,
+    default: () => []
+  }
+})
+
+const { t } = useI18n()
+const currentStep = ref(1)
+const isFinished = ref(false)
+const stepCount = computed(() => props.steps.length)
+
+watch(stepCount, (count) => {
+  if (count < 1) {
+    currentStep.value = 1
+    isFinished.value = false
+    return
+  }
+
+  if (currentStep.value > count) {
+    currentStep.value = count
+  }
+}, { immediate: true })
+
+const isLastStep = (index) => index === props.steps.length - 1
+const hasDefaultIcon = (step) => typeof step?.icon === 'string' && step.icon !== '' && step.icon !== 'none'
+const stepPrefix = (step, index) => hasDefaultIcon(step) ? void 0 : String(index + 1)
+const isStepDone = (index) => isFinished.value || currentStep.value > index + 1
+
+const goToStep = (stepNumber) => {
+  if (stepNumber < 1 || stepNumber > props.steps.length) {
+    return
+  }
+
+  isFinished.value = false
+  currentStep.value = stepNumber
+}
+
+const finishStepper = () => {
+  isFinished.value = true
+  currentStep.value = null
+}
+</script>
+
+<template>
+<div v-if="steps.length" class="d-stepper">
+  <q-stepper
+    v-model="currentStep"
+    vertical
+    animated
+    flat
+    bordered
+    header-nav
+    color="primary"
+    active-color="primary"
+    done-color="positive"
+    inactive-color="grey-6"
+    class="d-stepper__shell"
+  >
+    <q-step
+      v-for="(step, index) in steps"
+      :key="`${step.title}-${index}`"
+      :name="index + 1"
+      :title="step.title"
+      :prefix="stepPrefix(step, index)"
+      :icon="step.icon || void 0"
+      :active-icon="step.activeIcon || step.icon || void 0"
+      :done-icon="step.doneIcon || step.icon || void 0"
+      :error-icon="step.errorIcon || step.icon || void 0"
+      :done="isStepDone(index)"
+      header-class="d-stepper__step-header"
+      class="d-stepper__step"
+    >
+      <div class="d-stepper__body">
+        <slot :step="step" :index="index" />
+      </div>
+
+      <q-stepper-navigation class="d-stepper__navigation">
+        <q-btn
+          v-if="!isLastStep(index)"
+          color="primary"
+          no-caps
+          unelevated
+          :label="t('page.stepper.continue')"
+          @click="goToStep(index + 2)"
+        />
+
+        <q-btn
+          v-else
+          color="positive"
+          no-caps
+          unelevated
+          :label="t('page.stepper.finish')"
+          @click="finishStepper"
+        />
+
+        <q-btn
+          v-if="index > 0"
+          unelevated
+          no-caps
+          class="d-stepper__back d-stepper__secondary-action"
+          :label="t('page.stepper.back')"
+          @click="goToStep(index)"
+        />
+      </q-stepper-navigation>
+    </q-step>
+  </q-stepper>
+</div>
+</template>
+
+<style lang="sass">
+body.body--light
+  --d-stepper-shell-bg: #fffdfa
+  --d-stepper-shell-border: rgba(123, 94, 45, 0.16)
+  --d-stepper-shell-shadow: rgba(94, 73, 37, 0.08)
+  --d-stepper-header-bg: rgba(255, 242, 212, 0.32)
+  --d-stepper-divider: rgba(123, 94, 45, 0.14)
+  --d-stepper-text-muted: #5f6772
+  --d-stepper-secondary-bg: rgba(123, 94, 45, 0.12)
+  --d-stepper-secondary-bg-hover: rgba(123, 94, 45, 0.18)
+  --d-stepper-secondary-text: #705420
+
+body.body--dark
+  --d-stepper-shell-bg: rgba(255, 248, 235, 0.04)
+  --d-stepper-shell-border: rgba(255, 235, 194, 0.12)
+  --d-stepper-shell-shadow: rgba(0, 0, 0, 0.28)
+  --d-stepper-header-bg: rgba(255, 240, 210, 0.04)
+  --d-stepper-divider: rgba(255, 235, 194, 0.08)
+  --d-stepper-text-muted: rgba(255, 255, 255, 0.72)
+  --d-stepper-secondary-bg: rgba(255, 235, 194, 0.1)
+  --d-stepper-secondary-bg-hover: rgba(255, 235, 194, 0.16)
+  --d-stepper-secondary-text: #f4ddb0
+
+.d-stepper
+  margin: 1.5rem 0
+
+.d-stepper__shell
+  border-radius: 20px
+  overflow: hidden
+  background: var(--d-stepper-shell-bg)
+  border-color: var(--d-stepper-shell-border)
+  box-shadow: 0 16px 36px var(--d-stepper-shell-shadow)
+
+.d-stepper__shell.q-stepper--vertical
+  .q-stepper__header
+    background: var(--d-stepper-header-bg)
+
+  .q-stepper__tab
+    min-height: 72px
+
+  .q-stepper__step-inner
+    border-top: 1px solid var(--d-stepper-divider)
+
+  .q-stepper__title
+    font-size: 1rem
+    font-weight: 700
+    line-height: 1.45
+
+  .q-stepper__caption
+    color: var(--d-stepper-text-muted)
+
+.d-stepper__step-header
+  font-weight: 700
+
+.d-stepper__body
+  min-width: 0
+  padding-top: 0.85rem
+
+  > :first-child
+    margin-top: 0
+
+  > :last-child
+    margin-bottom: 0
+
+.d-stepper__navigation
+  display: flex
+  flex-wrap: wrap
+  gap: 0.75rem
+  margin-top: 1rem
+
+.d-stepper__back
+  margin-left: 0 !important
+
+.d-stepper__secondary-action
+  background: var(--d-stepper-secondary-bg) !important
+  color: var(--d-stepper-secondary-text) !important
+
+  &:hover,
+  &:focus-visible
+    background: var(--d-stepper-secondary-bg-hover) !important
+
+@media (max-width: 599px)
+  .d-stepper__shell.q-stepper--vertical
+    .q-stepper__tab
+      min-height: 64px
+
+    .q-stepper__title
+      font-size: 0.97rem
+
+  .d-stepper__navigation
+    gap: 0.55rem
+</style>