@docsector/docsector-reader 3.2.0 → 3.2.2

package/src/components/page-section-tokens.js

@@ -1,5 +1,6 @@
 import MarkdownIt from 'markdown-it'
 import attrs from 'markdown-it-attrs'
+import GithubSlugger from 'github-slugger'
 import katex from 'katex'
 import texmath from 'markdown-it-texmath'
 
@@ -214,6 +215,97 @@ const parseTokenAttributes = (element) => {
   return parsed
 }
 
+const decodeHtmlEntities = (value = '') => {
+  return String(value)
+    .replace(/"/g, '"')
+    .replace(/'|'/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+}
+
+const escapeHtml = (value = '') => {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+const extractTagAttributes = (html = '', tagName = '') => {
+  const match = String(html).match(new RegExp(`<${tagName}\\b([^>]*)\\/?>(?![\\s\\S]*<${tagName}\\b)`, 'i'))
+
+  if (!match) {
+    return {}
+  }
+
+  return parseCustomTagAttributes(match[1])
+}
+
+const createImageTokenData = (mediaHtml = '', options = {}) => {
+  const {
+    captionHtml = '',
+    fallbackCaptionFromAlt = false
+  } = options
+  const attrs = extractTagAttributes(mediaHtml, 'img')
+  const alt = decodeHtmlEntities(attrs.alt || '')
+  const title = decodeHtmlEntities(attrs.title || '')
+
+  return {
+    tag: 'image',
+    content: String(mediaHtml).trim(),
+    alt,
+    title,
+    captionHtml: captionHtml !== ''
+      ? captionHtml
+      : (fallbackCaptionFromAlt ? escapeHtml(alt) : '')
+  }
+}
+
+const parseStandaloneImageToken = (content = '') => {
+  const trimmed = String(content).trim()
+
+  if (!trimmed.match(/^<img\b[^>]*\/?>(?:\s*)$/i)) {
+    return null
+  }
+
+  return createImageTokenData(trimmed, {
+    fallbackCaptionFromAlt: true
+  })
+}
+
+const parseFigureImageToken = (content = '') => {
+  const trimmed = String(content).trim()
+
+  if (!trimmed.match(/^<figure\b[\s\S]*<\/figure>$/i)) {
+    return null
+  }
+
+  const figureBody = trimmed
+    .replace(/^<figure\b[^>]*>/i, '')
+    .replace(/<\/figure>$/i, '')
+    .trim()
+  const figcaptionMatch = figureBody.match(/<figcaption\b[^>]*>([\s\S]*?)<\/figcaption>/i)
+  const mediaBody = figcaptionMatch
+    ? figureBody.replace(figcaptionMatch[0], '').trim()
+    : figureBody
+  const pictureMatch = mediaBody.match(/^<picture\b[\s\S]*?<\/picture>$/i)
+  const imgMatch = pictureMatch
+    ? pictureMatch[0].match(/<img\b[^>]*\/?>/i)
+    : mediaBody.match(/^<img\b[^>]*\/?>$/i)
+
+  if (!imgMatch) {
+    return null
+  }
+
+  const mediaHtml = pictureMatch ? pictureMatch[0] : imgMatch[0]
+
+  return createImageTokenData(mediaHtml, {
+    captionHtml: figcaptionMatch ? figcaptionMatch[1].trim() : ''
+  })
+}
+
 const parseFenceLanguage = (raw = '') => {
   const cleaned = String(raw)
     .replace(/:[^;]*;/g, ' ')
@@ -346,10 +438,24 @@ const normalizePageSectionSource = (source = '') => {
     .replace(/&amp;/g, '&')
 }
 
+const createParserState = () => ({
+  codeIndex: 0,
+  headingSlugger: new GithubSlugger()
+})
+
+const getHeadingAnchorId = (markdown, currentTag, element, env, parserState) => {
+  if (!currentTag || !currentTag.match(/^h[2-6]$/)) {
+    return ''
+  }
+
+  const headingText = markdown.renderer.renderInlineAsText(element.children || [], markdown.options, env).trim()
+  return parserState.headingSlugger.slug(headingText)
+}
+
 export const tokenizePageSectionSource = (source = '', options = {}) => {
   const {
     allowHeadingTokens = true,
-    parserState = { codeIndex: 0 }
+    parserState = createParserState()
   } = options
   const normalizedSource = normalizePageSectionSource(source)
   const { source: sourceWithShieldedCode, codeSegmentsMap } = shieldMarkdownCodeSegments(normalizedSource)
@@ -505,7 +611,9 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
       }
 
       switch (element.type) {
-        case 'inline':
+        case 'inline': {
+          const anchorId = getHeadingAnchorId(markdown, tag, element, markdownEnv, parserState)
+
           if (expandableMap.has(element.content.trim())) {
             const data = expandableMap.get(element.content.trim())
 
@@ -532,13 +640,27 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (tag === 'p') {
+            const imageToken = parseStandaloneImageToken(element.content)
+
+            if (imageToken !== null) {
+              tokens.push({
+                ...imageToken,
+                map: element.map
+              })
+              break
+            }
+          }
+
           tokens.push({
             tag,
             map: element.map,
+            anchorId,
             content: element.content,
             info: element.info
           })
           break
+        }
 
         case 'fence':
           pushSourceCodeToken(tokens, element, parserState)
@@ -551,36 +673,59 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           })
           break
 
-        case 'html_block':
+        case 'html_block': {
+          const figureImageToken = parseFigureImageToken(element.content)
+
+          if (figureImageToken !== null) {
+            tokens.push({
+              ...figureImageToken,
+              map: element.map
+            })
+            break
+          }
+
           tokens.push({
             tag: 'html',
             content: element.content
           })
           break
+        }
       }
-    } else if (level === 1) {
+    } else if (level > 0) {
       const parent = tokens[tokens.length - 1]
 
       switch (element.type) {
         case 'bullet_list_open':
-          tokens.push({
-            tag: 'ul',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'ul',
+              content: ''
+            })
+          } else {
+            parent.content += '<ul>'
+          }
           break
 
         case 'ordered_list_open':
-          tokens.push({
-            tag: 'ol',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'ol',
+              content: ''
+            })
+          } else {
+            parent.content += '<ol>'
+          }
           break
 
         case 'table_open':
-          tokens.push({
-            tag: 'table',
-            content: ''
-          })
+          if (level === 1) {
+            tokens.push({
+              tag: 'table',
+              content: ''
+            })
+          } else {
+            parent.content += '<table>'
+          }
           break
 
         case 'list_item_open':
@@ -618,6 +763,24 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           parent.content += '</li>'
           break
 
+        case 'bullet_list_close':
+          if (level > 1) {
+            parent.content += '</ul>'
+          }
+          break
+
+        case 'ordered_list_close':
+          if (level > 1) {
+            parent.content += '</ol>'
+          }
+          break
+
+        case 'table_close':
+          if (level > 1) {
+            parent.content += '</table>'
+          }
+          break
+
         case 'thead_close':
           parent.content += '</thead>'
           break

package/src/composables/useNavigator.js

@@ -9,13 +9,34 @@ export default function useNavigator() {
   const route = useRoute()
   const selected = ref(null)
 
+  const normalizeDomAnchorId = (id) => {
+    if (id === null || id === undefined || id === false) {
+      return ''
+    }
+
+    let normalized = String(id).replace(/^#+/g, '')
+
+    try {
+      normalized = decodeURIComponent(normalized)
+    } catch {
+      // Keep the raw fragment when it is not valid percent-encoding.
+    }
+
+    return normalized
+  }
+
+  const normalizeStoreAnchorId = (id) => {
+    const normalized = normalizeDomAnchorId(id)
+    return normalized === '0' ? 0 : normalized
+  }
+
   const register = (id) => {
-    store.commit('page/pushAnchors', id)
+    store.commit('page/pushAnchors', normalizeStoreAnchorId(id))
   }
 
   const index = (id, child = false) => {
     store.commit('page/pushNodes', {
-      id,
+      id: normalizeStoreAnchorId(id),
       label: selected.value,
       child,
       children: []
@@ -23,15 +44,17 @@ export default function useNavigator() {
   }
 
   const select = (id) => {
-    store.commit('page/setAnchor', Number(id))
-    store.commit('page/pushNodesExpanded', Number(id))
+    const normalized = normalizeStoreAnchorId(id)
+
+    store.commit('page/setAnchor', normalized)
+    store.commit('page/pushNodesExpanded', normalized)
   }
 
   const anchor = (id, toSelect = true) => {
     store.commit('page/setScrolling', false)
 
-    id = '' + id
-    const Anchor = document.getElementById(id)
+    const anchorId = normalizeDomAnchorId(id)
+    const Anchor = document.getElementById(anchorId)
 
     if (Anchor !== null && typeof Anchor === 'object') {
       const ScrollTarget = scroll.getScrollTarget(Anchor)
@@ -45,7 +68,7 @@ export default function useNavigator() {
     }
 
     if (toSelect) {
-      select(id)
+      select(anchorId)
     }
   }
 
@@ -60,12 +83,13 @@ export default function useNavigator() {
 
     for (let i = 0; i < anchors.length; i++) {
       const anchorId = anchors[i]
+      const domAnchorId = normalizeDomAnchorId(anchorId)
 
-      if (anchorId === 0) {
+      if (domAnchorId === '0') {
         continue
       }
 
-      const Anchor = document.getElementById(anchorId)
+      const Anchor = document.getElementById(domAnchorId)
       let AnchorOffsetTop = 20
       if (Anchor !== null && typeof Anchor === 'object') {
         AnchorOffsetTop = Anchor.offsetTop
@@ -78,24 +102,30 @@ export default function useNavigator() {
   }
 
   const navigate = (value, toAnchor = true) => {
+    const domAnchorId = normalizeDomAnchorId(value)
+    const currentRouteAnchorId = normalizeDomAnchorId(route.hash)
+
     if (toAnchor) {
-      if (('#' + value) === route.hash) {
-        anchor(value)
+      if (domAnchorId !== '' && domAnchorId === currentRouteAnchorId) {
+        anchor(domAnchorId)
         return
       } else if (value === null) {
-        anchor(selected.value, false)
+        anchor(store.state.page.anchor, false)
         return
       }
     }
 
-    router.push(route.path + '#' + value)
+    router.push({
+      path: route.path,
+      hash: domAnchorId === '' ? '' : `#${domAnchorId}`
+    })
 
     if (toAnchor) {
       if (Platform.is.desktop) {
-        anchor(value)
+        anchor(domAnchorId)
       } else {
         setTimeout(() => {
-          anchor(value)
+          anchor(domAnchorId)
         }, 600)
       }
     }

package/src/pages/404Page.vue

@@ -3,12 +3,12 @@
   <q-page class="row" padding>
     <q-scroll-area class="content col text-center">
       <p>
-        <img src="sad.svg" style="width:30vw;max-width:150px;" />
+        <img src="/sad.svg" alt="404 illustration" style="width:30vw;max-width:150px;" />
       </p>
       <p class="text-faded">Sorry, nothing here...
         <strong>(404)</strong>
       </p>
-      <q-btn color="secondary" style="width:200px;" @click="$router.go(-1)">Go back</q-btn>
+      <q-btn color="secondary" style="width:200px;" @click="$router.push('/')">Go home</q-btn>
     </q-scroll-area>
   </q-page>
 </q-page-container>

package/src/pages/Homepage.en-US.md

@@ -7,9 +7,9 @@ Docsector Reader is a documentation rendering engine built with Vue 3, Quasar v2
 - [Getting Started](/guide/getting-started/overview/)
 - [Configuration](/guide/configuration/overview/)
 - [Pages and Routing](/guide/pages-and-routing/overview/)
-- [Components](/manual/components/d-page/overview/)
-- [Composables](/manual/composables/use-navigator/overview/)
-- [Store Modules](/manual/store/modules/overview/)
+- [Basic](/manual/basic/d-menu/overview/)
+- [Content](/manual/content/blocks/paragraphs/overview/)
+- [Structures](/manual/content/structures/books/overview/)
 
 ## About
 

package/src/pages/Homepage.pt-BR.md

@@ -7,9 +7,9 @@ Docsector Reader e um motor de documentacao construído com Vue 3, Quasar v2 e V
 - [Comecando](/guide/getting-started/overview/)
 - [Configuracao](/guide/configuration/overview/)
 - [Paginas e Rotas](/guide/pages-and-routing/overview/)
-- [Componentes](/manual/components/d-page/overview/)
-- [Composables](/manual/composables/use-navigator/overview/)
-- [Modulos de Store](/manual/store/modules/overview/)
+- [Básico](/manual/basic/d-menu/overview/)
+- [Conteúdo](/manual/content/blocks/paragraphs/overview/)
+- [Estruturas](/manual/content/structures/books/overview/)
 
 ## Sobre
 

package/src/pages/guide/i18n-and-markdown.overview.en-US.md

@@ -41,9 +41,15 @@ The `_` object is the root namespace for pages. Page titles and content are **au
 
 Documentation content is written in standard Markdown with some conventions:
 
+See the dedicated manual pages for block-by-block reference:
+
+- [Paragraphs](/manual/content/blocks/paragraphs/overview/), [Headings](/manual/content/blocks/headings/overview/), [Unordered lists](/manual/content/blocks/unordered-lists/overview/), [Ordered lists](/manual/content/blocks/ordered-lists/overview/)
+- [Hints](/manual/content/blocks/hints/overview/), [Quote](/manual/content/blocks/quotes/overview/), [Code blocks](/manual/content/blocks/code-blocks/overview/), [Mermaid diagrams](/manual/content/blocks/mermaid-diagrams/overview/)
+- [Images](/manual/content/blocks/images/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expandable](/manual/content/blocks/expandable/overview/), [Tables](/manual/content/blocks/tables/overview/), [Raw HTML](/manual/content/blocks/raw-html/overview/), and [Quick Links](/manual/content/blocks/quick-links/overview/)
+
 ### Headings
 
-Use `##` through `######` for section headings. Each heading becomes a navigation anchor in the ToC tree.
+Use `##` through `######` for section headings. Each heading becomes a navigation anchor in the ToC tree using a GitHub-compatible slug, so standard README fragments such as `#table-of-contents` work in Docsector too.
 
 ### Code Blocks
 

package/src/pages/guide/i18n-and-markdown.overview.pt-BR.md

@@ -41,9 +41,15 @@ O objeto `_` é o namespace raiz para páginas. Títulos e conteúdo das página
 
 O conteúdo da documentação é escrito em Markdown padrão com algumas convenções:
 
+Veja também as páginas dedicadas do manual para cada bloco:
+
+- [Parágrafos](/manual/content/blocks/paragraphs/overview/), [Títulos](/manual/content/blocks/headings/overview/), [Listas não ordenadas](/manual/content/blocks/unordered-lists/overview/), [Listas ordenadas](/manual/content/blocks/ordered-lists/overview/)
+- [Hints](/manual/content/blocks/hints/overview/), [Citação](/manual/content/blocks/quotes/overview/), [Blocos de código](/manual/content/blocks/code-blocks/overview/), [Diagramas Mermaid](/manual/content/blocks/mermaid-diagrams/overview/)
+- [Imagens](/manual/content/blocks/images/overview/), [Math & TeX](/manual/content/blocks/math-and-tex/overview/), [Expansível](/manual/content/blocks/expandable/overview/), [Tabelas](/manual/content/blocks/tables/overview/), [HTML bruto](/manual/content/blocks/raw-html/overview/) e [Quick Links](/manual/content/blocks/quick-links/overview/)
+
 ### Títulos
 
-Use `##` até `######` para títulos de seção. Cada título se torna uma âncora de navegação na árvore de ToC.
+Use `##` até `######` para títulos de seção. Cada título se torna uma âncora de navegação na árvore de ToC usando slug compatível com GitHub, então fragmentos padrão de README como `#table-of-contents` também funcionam no Docsector.
 
 ### Blocos de Código
 

package/src/pages/guide/pages-and-routing.overview.en-US.md

@@ -2,6 +2,8 @@
 
 Documentation pages are defined in split registries such as `src/pages/guide.index.js` and `src/pages/manual.index.js`. Each entry maps a URL path to its configuration, translatable data, and optional metadata.
 
+In the current manual, it is common to keep core UI references under `/basic`, end-user content blocks under `/content/blocks`, structural concepts under `/content/structures`, and legacy engine-facing aliases under `/components`.
+
 ## Page Entry Structure
 
 ```javascript
@@ -35,11 +37,11 @@ Documentation pages are defined in split registries such as `src/pages/guide.ind
 Set `config: null` to create a non-navigable grouping node. This is useful for creating section titles in the sidebar menu:
 
 ```javascript
-'/components': {
+'/content/blocks': {
   config: null,
   data: {
-    'en-US': { title: 'Components' },
-    'pt-BR': { title: 'Componentes' }
+    'en-US': { title: 'Blocks' },
+    'pt-BR': { title: 'Blocos' }
   }
 }
 ```
@@ -51,8 +53,8 @@ Pages are grouped in the sidebar by their **basepath** (second URL segment). The
 ```javascript
 menu: {
   header: {
-    icon: 'widgets',
-    label: 'Components'
+    icon: 'notes',
+    label: 'Content'
   }
 }
 ```
@@ -72,11 +74,11 @@ Each page requires Markdown files following this naming pattern:
 
 `src/pages/{book}/{path}.{subpage}.{lang}.md`
 
-For example, a page at `/components/d-page` with book `manual`:
+For example, a page at `/content/blocks/headings` with book `manual`:
 
-- `src/pages/manual/components/d-page.overview.en-US.md`
-- `src/pages/manual/components/d-page.overview.pt-BR.md`
-- `src/pages/manual/components/d-page.showcase.en-US.md` (if showcase enabled)
+- `src/pages/manual/content/blocks/headings.overview.en-US.md`
+- `src/pages/manual/content/blocks/headings.overview.pt-BR.md`
+- `src/pages/manual/content/blocks/headings.showcase.en-US.md` (if showcase enabled)
 
 ## Route Generation
 

package/src/pages/guide/pages-and-routing.overview.pt-BR.md

@@ -2,6 +2,8 @@
 
 As páginas de documentação são definidas em registros separados, como `src/pages/guide.index.js` e `src/pages/manual.index.js`. Cada entrada mapeia um caminho URL para sua configuração, dados traduzíveis e metadata opcional.
 
+No manual atual, é comum manter referências centrais de UI sob `/basic`, blocos de conteúdo voltados ao usuário final sob `/content/blocks`, conceitos estruturais sob `/content/structures` e aliases legados voltados à engine sob `/components`.
+
 ## Estrutura de uma Entrada
 
 ```javascript
@@ -35,11 +37,11 @@ As páginas de documentação são definidas em registros separados, como `src/p
 Defina `config: null` para criar um nó de agrupamento não-navegável. Útil para criar títulos de seção no menu lateral:
 
 ```javascript
-'/components': {
+'/content/blocks': {
   config: null,
   data: {
-    'en-US': { title: 'Components' },
-    'pt-BR': { title: 'Componentes' }
+    'en-US': { title: 'Blocks' },
+    'pt-BR': { title: 'Blocos' }
   }
 }
 ```
@@ -51,8 +53,8 @@ Páginas são agrupadas no menu lateral pelo seu **basepath** (segundo segmento
 ```javascript
 menu: {
   header: {
-    icon: 'widgets',
-    label: 'Components'
+    icon: 'notes',
+    label: 'Conteúdo'
   }
 }
 ```
@@ -72,11 +74,11 @@ Cada página requer arquivos Markdown seguindo este padrão de nomenclatura:
 
 `src/pages/{book}/{path}.{subpage}.{lang}.md`
 
-Por exemplo, uma página em `/components/d-page` com book `manual`:
+Por exemplo, uma página em `/content/blocks/headings` com book `manual`:
 
-- `src/pages/manual/components/d-page.overview.en-US.md`
-- `src/pages/manual/components/d-page.overview.pt-BR.md`
-- `src/pages/manual/components/d-page.showcase.en-US.md` (se showcase habilitado)
+- `src/pages/manual/content/blocks/headings.overview.en-US.md`
+- `src/pages/manual/content/blocks/headings.overview.pt-BR.md`
+- `src/pages/manual/content/blocks/headings.showcase.en-US.md` (se showcase habilitado)
 
 ## Geração de Rotas
 

package/src/pages/guide.index.js

@@ -120,34 +120,6 @@ export default {
     }
   },
 
-  '/alerts-and-blockquotes': {
-    config: {
-      icon: 'notification_important',
-      status: 'done',
-      meta: {
-        description: {
-          'en-US': 'Alerts & Blockquotes — Documentation of Docsector Reader',
-          'pt-BR': 'Alertas & Blockquotes — Documentacao do Docsector Reader'
-        }
-      },
-      book: 'guide',
-      menu: {},
-      subpages: {
-        showcase: false
-      }
-    },
-    data: {
-      'en-US': { title: 'Alerts & Blockquotes' },
-      'pt-BR': { title: 'Alertas & Blockquotes' }
-    },
-    metadata: {
-      tags: {
-        'en-US': 'alerts blockquotes github note tip important warning caution markdown quote admonition',
-        'pt-BR': 'alertas blockquotes github note tip important warning caution markdown citação admonition'
-      }
-    }
-  },
-
   '/theming': {
     config: {
       icon: 'palette',

package/src/pages/manual/basic/branding.overview.en-US.md

@@ -0,0 +1,27 @@
+## Overview
+
+Branding controls the visual identity and quick-access links shown at the top of the documentation menu.
+
+It covers the project logo, name, current version label, and the external links that appear below the branding block.
+
+## Main Configuration
+
+Branding data comes from `docsector.config.js`:
+
+- `branding.logo`
+- `branding.name`
+- `branding.version`
+- `links.github`, `links.discussions`, `links.chat`, `links.email`
+- `links.changelog`, `links.roadmap`, `links.sponsor`, `links.explore`
+
+## What Readers Notice
+
+- A recognizable project identity in the menu
+- Faster access to repository and community links
+- A stable place to understand which docs set they are reading
+
+## Notes
+
+- Set a link to `null` to hide it from the menu.
+- A square or near-square logo usually fits best in the sidebar.
+- Keep the visible project name short enough to scan quickly.

package/src/pages/manual/basic/branding.overview.pt-BR.md

@@ -0,0 +1,27 @@
+## Visão Geral
+
+Branding controla a identidade visual e os links de acesso rápido exibidos no topo do menu da documentação.
+
+Ele cobre o logo do projeto, o nome, o label da versão atual e os links externos que aparecem abaixo do bloco de branding.
+
+## Configuração Principal
+
+Os dados de branding vêm de `docsector.config.js`:
+
+- `branding.logo`
+- `branding.name`
+- `branding.version`
+- `links.github`, `links.discussions`, `links.chat`, `links.email`
+- `links.changelog`, `links.roadmap`, `links.sponsor`, `links.explore`
+
+## O Que o Leitor Percebe
+
+- Uma identidade reconhecível do projeto no menu
+- Acesso mais rápido ao repositório e aos links da comunidade
+- Um lugar estável para entender qual conjunto de docs está sendo lido
+
+## Observações
+
+- Defina um link como `null` para escondê-lo do menu.
+- Um logo quadrado ou quase quadrado costuma funcionar melhor na barra lateral.
+- Mantenha o nome visível do projeto curto o suficiente para leitura rápida.