@docsector/docsector-reader 4.0.0 → 4.1.0

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
@@ -79,6 +79,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🗃️ **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
 - 🏷️ **Version Selector Badges** — Every version in the sidebar selector displays a color-coded badge: green for released, orange for draft, red for deprecated; fully customizable via `badge: { label, color, textColor }`
 - 📂 **Tabbed Code Blocks** — Group consecutive fenced code blocks into tabs using the `group` and `tab` attributes in the fence info line
+- 🧪 **Live Code Example Blocks** — Use `<d-block-code-example src="..." />` to render bundled Vue SFC examples with a live preview, GitHub source link, source toggle, and CodePen export for compatible examples
 - 🍞 **Breadcrumb Path Display** — Show a file path breadcrumb above code blocks with the `breadcrumb` attribute; renders as clickable path segments
 - 🎨 **File Type Icons** — Automatically resolves file extension or filename to a Material Icon Theme SVG icon, shown inline in tabs and beside the last breadcrumb segment
 - ⚙️ **Single Config File** — Customize branding, links, and languages via `docsector.config.js`
@@ -360,7 +361,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
@@ -1022,6 +1024,22 @@ Notes:
 Supported alert types: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`.
 Regular blockquotes without `[!TYPE]` continue to work normally.
 
+### Code Example Blocks
+
+```html
+<d-block-code-example src="manual/code-examples/basic-counter" title="Basic counter">
+Optional caption rendered as inline Markdown.
+</d-block-code-example>
+```
+
+Notes:
+
+- Store live examples as Vue SFCs under `src/examples/**/*.vue`; for example, `src="manual/code-examples/basic-counter"` resolves `src/examples/manual/code-examples/BasicCounter.vue` after kebab-case normalization.
+- Readers get a live preview, a GitHub button for the example SFC, a source button with Template / Script / Style / All tabs, and a CodePen button when the example can be exported safely.
+- Use `expanded="true"` only when the source code should be visible by default.
+- CodePen export currently supports plain Vue SFCs with a template, optional style, and an Options API `export default` script. Named imports from `vue` and `quasar` are converted to browser globals.
+- Examples using `<script setup>`, TypeScript scripts, or local imports still render in Docsector, but the CodePen action is disabled. Use `codepen="false"` to hide it intentionally.
+
 ### File Attachment Blocks
 
 ```html

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.1.0'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/package.json

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

@@ -0,0 +1,423 @@
+<script setup>
+import { computed, markRaw, ref, watch } from 'vue'
+import { openURL, Quasar, useQuasar } from 'quasar'
+
+import { resolveCodeExample } from 'virtual:docsector-code-examples'
+import docsectorConfig from 'docsector.config.js'
+
+import DBlockSourceCode from './DBlockSourceCode.vue'
+import {
+  canCreateCodepenPayload,
+  createCodeExampleGitHubUrl,
+  createCodeExampleTabs,
+  createCodepenPayload,
+  getCodepenUnsupportedReason
+} from './code-example-source'
+
+defineOptions({
+  name: 'DBlockCodeExample'
+})
+
+const props = defineProps({
+  index: {
+    type: Number,
+    required: true
+  },
+  src: {
+    type: String,
+    default: ''
+  },
+  title: {
+    type: String,
+    default: ''
+  },
+  caption: {
+    type: String,
+    default: ''
+  },
+  expanded: {
+    type: Boolean,
+    default: false
+  },
+  codepen: {
+    type: Boolean,
+    default: true
+  },
+  scrollable: {
+    type: Boolean,
+    default: false
+  },
+  overflow: {
+    type: Boolean,
+    default: false
+  },
+  height: {
+    type: String,
+    default: ''
+  }
+})
+
+const $q = useQuasar()
+
+const isBusy = ref(false)
+const errorMessage = ref('')
+const component = ref(null)
+const sourceText = ref('')
+const sourceTabs = ref([])
+const sourceOpen = ref(props.expanded)
+const exampleFilePath = ref('')
+let requestIndex = 0
+
+const displayTitle = computed(() => props.title || props.src || 'Code example')
+const frameTone = computed(() => $q.dark.isActive ? 'dark' : 'light')
+const hasSource = computed(() => sourceText.value.trim().length > 0)
+const codepenUnsupportedReason = computed(() => {
+  if (!hasSource.value) {
+    return 'Source code is still loading.'
+  }
+
+  return getCodepenUnsupportedReason(sourceText.value)
+})
+const canOpenCodepen = computed(() => props.codepen && hasSource.value && canCreateCodepenPayload(sourceText.value))
+const codepenTooltip = computed(() => canOpenCodepen.value ? 'Edit in CodePen' : codepenUnsupportedReason.value)
+const githubUrl = computed(() => createCodeExampleGitHubUrl(exampleFilePath.value, docsectorConfig))
+const canOpenGitHub = computed(() => githubUrl.value !== '')
+const previewStyle = computed(() => {
+  const style = {}
+  const normalizedHeight = normalizeCssLength(props.height)
+
+  if (normalizedHeight) {
+    style.height = normalizedHeight
+  } else if (props.scrollable) {
+    style.height = '500px'
+  }
+
+  return style
+})
+
+watch(() => props.expanded, (value) => {
+  sourceOpen.value = value
+})
+
+watch(() => props.src, () => {
+  loadExample()
+}, { immediate: true })
+
+function normalizeCssLength (value = '') {
+  const normalized = String(value || '').trim()
+
+  if (!normalized) {
+    return ''
+  }
+
+  if (/^-?\d+(?:\.\d+)?$/.test(normalized)) {
+    return `${normalized}px`
+  }
+
+  return normalized
+}
+
+async function loadExample () {
+  const currentRequest = ++requestIndex
+  const resolved = resolveCodeExample(props.src)
+
+  isBusy.value = true
+  errorMessage.value = ''
+  component.value = null
+  sourceText.value = ''
+  sourceTabs.value = []
+  exampleFilePath.value = ''
+
+  if (!props.src) {
+    errorMessage.value = 'Code example source is missing.'
+    isBusy.value = false
+    return
+  }
+
+  if (!resolved.exists || typeof resolved.loadComponent !== 'function' || typeof resolved.loadSource !== 'function') {
+    errorMessage.value = `Code example not found: ${resolved.id || props.src}`
+    isBusy.value = false
+    return
+  }
+
+  try {
+    const [componentModule, rawSource] = await Promise.all([
+      resolved.loadComponent(),
+      resolved.loadSource()
+    ])
+
+    if (currentRequest !== requestIndex) {
+      return
+    }
+
+    component.value = markRaw(componentModule.default || componentModule)
+    sourceText.value = String(rawSource || '')
+    sourceTabs.value = createCodeExampleTabs(sourceText.value)
+    exampleFilePath.value = resolved.filePath || ''
+  } catch (err) {
+    if (currentRequest !== requestIndex) {
+      return
+    }
+
+    errorMessage.value = err?.message || `Unable to load code example: ${props.src}`
+  } finally {
+    if (currentRequest === requestIndex) {
+      isBusy.value = false
+    }
+  }
+}
+
+function toggleSource () {
+  sourceOpen.value = !sourceOpen.value
+}
+
+function submitCodepenPayload (payload) {
+  if (typeof document === 'undefined') {
+    return
+  }
+
+  const form = document.createElement('form')
+  const input = document.createElement('input')
+
+  form.method = 'post'
+  form.action = 'https://codepen.io/pen/define/'
+  form.target = '_blank'
+  form.rel = 'noopener'
+  form.style.display = 'none'
+
+  input.type = 'hidden'
+  input.name = 'data'
+  input.value = JSON.stringify(payload)
+
+  form.appendChild(input)
+  document.body.appendChild(form)
+  form.submit()
+  form.remove()
+}
+
+function openCodepen () {
+  if (!canOpenCodepen.value) {
+    return
+  }
+
+  const sourceUrl = typeof window === 'undefined'
+    ? ''
+    : `${window.location.origin}${window.location.pathname}${window.location.hash}`
+
+  submitCodepenPayload(createCodepenPayload(sourceText.value, {
+    title: displayTitle.value,
+    quasarVersion: Quasar.version,
+    sourceUrl
+  }))
+}
+
+function openGitHub () {
+  if (canOpenGitHub.value) {
+    openURL(githubUrl.value)
+  }
+}
+</script>
+
+<template>
+<div
+  class="d-block-code-example"
+  :class="`d-block-code-example--${frameTone}`"
+>
+  <div class="d-block-code-example__toolbar">
+    <div class="d-block-code-example__title">{{ displayTitle }}</div>
+
+    <q-space />
+
+    <q-btn
+      class="d-block-code-example__button"
+      dense
+      flat
+      round
+      icon="fab fa-github"
+      :disable="!canOpenGitHub"
+      aria-label="View example on GitHub"
+      @click="openGitHub"
+    >
+      <q-tooltip>{{ canOpenGitHub ? 'View on GitHub' : 'GitHub source is unavailable' }}</q-tooltip>
+    </q-btn>
+
+    <q-btn
+      v-if="codepen"
+      class="d-block-code-example__button"
+      dense
+      flat
+      round
+      icon="fab fa-codepen"
+      :disable="!canOpenCodepen"
+      aria-label="Edit in CodePen"
+      @click="openCodepen"
+    >
+      <q-tooltip>{{ codepenTooltip }}</q-tooltip>
+    </q-btn>
+
+    <q-btn
+      class="d-block-code-example__button"
+      dense
+      flat
+      round
+      icon="code"
+      :disable="!hasSource"
+      :aria-label="sourceOpen ? 'Hide source' : 'View source'"
+      @click="toggleSource"
+    >
+      <q-tooltip>{{ sourceOpen ? 'Hide source' : 'View source' }}</q-tooltip>
+    </q-btn>
+  </div>
+
+  <q-slide-transition>
+    <div
+      v-show="sourceOpen && hasSource"
+      class="d-block-code-example__source"
+    >
+      <d-block-source-code
+        :index="index"
+        language="vue"
+        :text="sourceText"
+        :tabs="sourceTabs"
+      />
+    </div>
+  </q-slide-transition>
+
+  <q-linear-progress
+    v-if="isBusy"
+    color="primary"
+    indeterminate
+  />
+
+  <div
+    class="d-block-code-example__preview"
+    :class="{
+      'd-block-code-example__preview--scrollable': scrollable,
+      'd-block-code-example__preview--overflow': overflow
+    }"
+    :style="previewStyle"
+  >
+    <component
+      v-if="component && !errorMessage"
+      :is="component"
+      class="d-block-code-example__component"
+    />
+
+    <div
+      v-else-if="errorMessage"
+      class="d-block-code-example__fallback"
+    >
+      <q-icon
+        name="warning"
+        size="22px"
+      />
+      <span>{{ errorMessage }}</span>
+    </div>
+  </div>
+
+  <div
+    v-if="caption"
+    class="d-block-code-example__caption"
+    v-html="caption"
+  ></div>
+</div>
+</template>
+
+<style lang="sass">
+body.body--light
+  --d-code-example-bg: #ffffff
+  --d-code-example-border: rgba(37, 67, 45, 0.16)
+  --d-code-example-toolbar-bg: #f6f8f5
+  --d-code-example-toolbar-text: #26352b
+  --d-code-example-preview-bg: #ffffff
+  --d-code-example-caption: #405148
+  --d-code-example-muted: #5d7563
+
+body.body--dark
+  --d-code-example-bg: #111512
+  --d-code-example-border: rgba(197, 220, 200, 0.18)
+  --d-code-example-toolbar-bg: #1a211c
+  --d-code-example-toolbar-text: #e8efe9
+  --d-code-example-preview-bg: #0c0f0d
+  --d-code-example-caption: #c7d4ca
+  --d-code-example-muted: #9aafa0
+
+.d-block-code-example
+  background: var(--d-code-example-bg)
+  border: 1px solid var(--d-code-example-border)
+  border-radius: 6px
+  box-shadow: 0 1px 1px rgb(0 0 0 / 8%)
+  margin: 18px 0
+  max-width: calc(100vw - 40px)
+  overflow: hidden
+
+  &__toolbar
+    align-items: center
+    background: var(--d-code-example-toolbar-bg)
+    color: var(--d-code-example-toolbar-text)
+    display: flex
+    gap: 4px
+    min-height: 42px
+    min-width: 0
+    padding: 4px 8px 4px 14px
+
+  &__title
+    font-size: 14px
+    font-weight: 600
+    line-height: 20px
+    min-width: 0
+    overflow: hidden
+    text-overflow: ellipsis
+    white-space: nowrap
+
+  &__button
+    color: var(--d-code-example-muted)
+    flex: 0 0 auto
+
+  &__source
+    border-top: 1px solid var(--d-code-example-border)
+
+    .source-code
+      box-shadow: none
+      margin: 0
+      max-width: 100%
+
+      .source-code-frame
+        border: 0
+        border-radius: 0
+
+  &__preview
+    background: var(--d-code-example-preview-bg)
+    min-height: 96px
+    min-width: 0
+    overflow: hidden
+    position: relative
+
+    &--scrollable
+      overflow-y: auto
+
+    &--overflow
+      overflow: auto
+
+  &__component
+    display: block
+    min-width: 0
+
+  &__fallback
+    align-items: center
+    color: var(--d-code-example-muted)
+    display: flex
+    gap: 8px
+    min-height: 96px
+    padding: 18px
+
+  &__caption
+    border-top: 1px solid var(--d-code-example-border)
+    color: var(--d-code-example-caption)
+    font-size: 14px
+    line-height: 1.55
+    padding: 10px 14px 12px
+
+    p
+      margin: 0
+</style>

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/DBlockSourceCode.vue

@@ -2,13 +2,7 @@
 import { ref, computed, watch } from 'vue'
 import { useQuasar } from 'quasar'
 import { useStore } from 'vuex'
-import Prism from 'prismjs'
-// @ Load Prism languages
-import 'prismjs/components/prism-markup-templating' // dependency for prism-php extension
-// PHP
-import 'prismjs/components/prism-php'
-// Bash
-import 'prismjs/components/prism-bash'
+import Prism from './code-block-highlighting'
 import { looksLikeFileName, resolveFileIconUrl } from '../composables/useFileIcon'
 
 defineOptions({

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: () => []
@@ -30,12 +34,18 @@ import DBlockQuickLinks from './DBlockQuickLinks.vue'
 import DBlockTimeline from './DBlockTimeline.vue'
 import DBlockExpandable from './DBlockExpandable.vue'
 import DBlockStepper from './DBlockStepper.vue'
+import DBlockCodeExample from './DBlockCodeExample.vue'
 </script>
 
 <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"
   />
@@ -126,6 +136,19 @@ import DBlockStepper from './DBlockStepper.vue'
     :tabs="token.tabs"
   />
 
+  <d-block-code-example
+    v-else-if="token.tag === 'code-example'"
+    :index="id + token.codeIndex"
+    :src="token.src"
+    :title="token.title"
+    :caption="token.caption"
+    :expanded="token.expanded"
+    :codepen="token.codepen"
+    :scrollable="token.scrollable"
+    :overflow="token.overflow"
+    :height="token.height"
+  />
+
   <d-block-mermaid-diagram
     v-else-if="token.tag === 'mermaid'"
     :content="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/components/code-block-highlighting.js

@@ -0,0 +1,16 @@
+import Prism from 'prismjs'
+
+import 'prismjs/components/prism-markup'
+import 'prismjs/components/prism-markup-templating'
+import 'prismjs/components/prism-javascript'
+import 'prismjs/components/prism-css'
+import 'prismjs/components/prism-php'
+import 'prismjs/components/prism-bash'
+
+if (!Prism.languages.vue && Prism.languages.markup?.tag?.addInlined) {
+	Prism.languages.markup.tag.addInlined('script', 'javascript')
+	Prism.languages.markup.tag.addInlined('style', 'css')
+	Prism.languages.vue = Prism.languages.markup
+}
+
+export default Prism