@docsector/docsector-reader 3.3.1 → 3.4.0

package/README.md

@@ -42,6 +42,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 
 - 📝 **Markdown Rendering** — Write docs in Markdown, rendered with syntax highlighting (Prism.js)
 - 🔽 **Nested Markdown Lists** — Ordered and unordered lists preserve sublist hierarchy across multiple indentation levels
+- ☑️ **Markdown Task Lists** — GitBook-style `- [ ]` and `- [x]` items render as read-only checkboxes with nested subtasks
 - 🖼️ **Block Image Captions & Zoom** — Standalone Markdown images render as zoomable figures, and raw `figure` / `picture` markup supports separate alt text and captions
 - 🧱 **Raw HTML in Markdown** — Renders inline and block HTML tags inside markdown sections (including homepage remote README content)
 - 🧩 **Mermaid Diagrams** — Native support for fenced ` ```mermaid ` blocks, with automatic dark/light theme switching

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.3.1",
+  "version": "3.4.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",
@@ -74,6 +74,7 @@
     "katex": "^0.17.0",
     "markdown-it": "^13.0.1",
     "markdown-it-attrs": "^4.1.6",
+    "markdown-it-task-lists": "^2.1.1",
     "markdown-it-texmath": "^1.0.0",
     "mermaid": "^11.0.0",
     "prismjs": "^1.27.0",

package/src/components/DPageTokens.vue

@@ -58,10 +58,12 @@ import DPageExpandable from './DPageExpandable.vue'
 
   <ul
     v-else-if="token.tag === 'ul'"
+    v-bind="token.attrs || {}"
     v-html="token.content"
   ></ul>
   <ol
     v-else-if="token.tag === 'ol'"
+    v-bind="token.attrs || {}"
     v-html="token.content"
   ></ol>
 

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

@@ -2,6 +2,7 @@ import MarkdownIt from 'markdown-it'
 import attrs from 'markdown-it-attrs'
 import GithubSlugger from 'github-slugger'
 import katex from 'katex'
+import taskLists from 'markdown-it-task-lists'
 import texmath from 'markdown-it-texmath'
 
 const ALERT_MESSAGE_TYPES = new Set([
@@ -114,6 +115,32 @@ const restoreShieldedCodeSegments = (source = '', codeSegmentsMap = new Map()) =
   return restored
 }
 
+const escapeHtmlAttributeValue = (value = '') => {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+}
+
+const getTokenAttributes = (element) => {
+  if (!Array.isArray(element?.attrs) || element.attrs.length === 0) {
+    return null
+  }
+
+  return Object.fromEntries(element.attrs.map(([name, value]) => [name, value ?? '']))
+}
+
+const renderTokenAttributes = (element) => {
+  const attributes = getTokenAttributes(element)
+
+  if (attributes === null) {
+    return ''
+  }
+
+  return Object.entries(attributes)
+    .map(([name, value]) => ` ${name}="${escapeHtmlAttributeValue(value)}"`)
+    .join('')
+}
+
 const extractQuickLinksBlocks = (source = '') => {
   const map = new Map()
   let index = 0
@@ -468,6 +495,14 @@ const renderBlockToken = (markdown, element, env) => {
   return markdown.renderer.render([element], markdown.options, env).trim()
 }
 
+const renderInlineToken = (markdown, markdownInline, element, env) => {
+  if (Array.isArray(element.children) && element.children.length > 0) {
+    return markdown.renderer.renderInline(element.children, markdown.options, env)
+  }
+
+  return markdownInline.renderInline(element.content, env)
+}
+
 const createMarkdownBlockParser = () => {
   const markdown = installMathSupport(new MarkdownIt({
     html: true
@@ -478,6 +513,11 @@ const createMarkdownBlockParser = () => {
     rightDelimiter: ';',
     allowedAttributes: ['filename', 'group', 'tab', 'breadcrumb']
   })
+  markdown.use(taskLists, {
+    enabled: false,
+    label: false,
+    labelAfter: false
+  })
 
   return markdown
 }
@@ -662,7 +702,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
     }
 
     if (element.type === 'inline') {
-      element.content = markdownInline.renderInline(element.content, markdownEnv)
+      element.content = renderInlineToken(markdown, markdownInline, element, markdownEnv)
     }
 
     if (level === 0) {
@@ -779,23 +819,29 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
       switch (element.type) {
         case 'bullet_list_open':
           if (level === 1) {
+            const attributes = getTokenAttributes(element)
+
             tokens.push({
               tag: 'ul',
-              content: ''
+              content: '',
+              ...(attributes !== null ? { attrs: attributes } : {})
             })
           } else {
-            parent.content += '<ul>'
+            parent.content += `<ul${renderTokenAttributes(element)}>`
           }
           break
 
         case 'ordered_list_open':
           if (level === 1) {
+            const attributes = getTokenAttributes(element)
+
             tokens.push({
               tag: 'ol',
-              content: ''
+              content: '',
+              ...(attributes !== null ? { attrs: attributes } : {})
             })
           } else {
-            parent.content += '<ol>'
+            parent.content += `<ol${renderTokenAttributes(element)}>`
           }
           break
 
@@ -811,7 +857,7 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
           break
 
         case 'list_item_open':
-          parent.content += '<li>'
+          parent.content += `<li${renderTokenAttributes(element)}>`
           break
 
         case 'thead_open':

package/src/css/app.sass

@@ -15,6 +15,11 @@ body
 body.body--light
   --q-primary: #655529 !important
   --q-secondary: #000080 !important
+  --task-list-checkbox-bg: #ffffff
+  --task-list-checkbox-border: #7c6a3a
+  --task-list-checkbox-checked-bg: #5e4c1f
+  --task-list-checkbox-checked-border: #4f3f18
+  --task-list-checkbox-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='%23ffffff' stroke-linecap='round' stroke-linejoin='round' stroke-width='2.3' d='M3.25 8.5 6.4 11.4 12.75 4.9'/%3E%3C/svg%3E")
 
   --q-primary-background: #FFF !important
 
@@ -48,6 +53,11 @@ body.body--dark
   --q-primary-in-dark-bg: #C1A667 !important
   --q-secondary: #FFA07A !important
   --q-negative: #fc001b !important
+  --task-list-checkbox-bg: #181818
+  --task-list-checkbox-border: #8f8a78
+  --task-list-checkbox-checked-bg: #d3b874
+  --task-list-checkbox-checked-border: #ebd08a
+  --task-list-checkbox-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='%23151515' stroke-linecap='round' stroke-linejoin='round' stroke-width='2.3' d='M3.25 8.5 6.4 11.4 12.75 4.9'/%3E%3C/svg%3E")
 
   --q-light-in-dark-1: #ababab
   --q-light-in-dark-2: #c9c9c9
@@ -199,6 +209,39 @@ body.body--dark
     overflow-y: hidden
     padding: 0.35rem 0.1rem
 
+  ul.contains-task-list,
+  ol.contains-task-list
+    list-style: none
+    padding-left: 1.75rem
+
+  li.task-list-item
+    list-style: none
+
+  input.task-list-item-checkbox
+    appearance: none
+    -webkit-appearance: none
+    width: 1rem
+    height: 1rem
+    margin: 0 0.55rem 0 -1.45rem
+    vertical-align: middle
+    pointer-events: none
+    opacity: 1
+    border: 2px solid var(--task-list-checkbox-border)
+    border-radius: 0.2rem
+    background-color: var(--task-list-checkbox-bg)
+    background-position: center
+    background-repeat: no-repeat
+    background-size: 0.72rem 0.72rem
+    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.08)
+
+    &:checked
+      background-color: var(--task-list-checkbox-checked-bg)
+      border-color: var(--task-list-checkbox-checked-border)
+      background-image: var(--task-list-checkbox-check)
+
+    &:disabled
+      opacity: 1
+
   a
     text-decoration: none
     outline: 0

package/src/pages/manual/content/blocks/task-lists.overview.en-US.md

@@ -0,0 +1,20 @@
+## Overview
+
+Use task lists when each item should carry an explicit done or not-done state.
+
+They work well for release preparation, editorial queues, migration follow-ups, and any checklist where progress matters as much as the content itself.
+
+## Markdown Syntax
+
+```markdown
+- [ ] Write the overview page
+- [x] Add localized examples
+  - [ ] Review screenshots
+  - [x] Update internal links
+```
+
+## Notes
+
+- Task lists follow the same indentation rules as regular Markdown lists.
+- Use `[ ]` for pending items and `[x]` for completed items.
+- Published readers see static checkboxes and cannot toggle them from the page.

package/src/pages/manual/content/blocks/task-lists.overview.pt-BR.md

@@ -0,0 +1,20 @@
+## Visão Geral
+
+Use listas de tarefas quando cada item precisar deixar explícito se foi concluído ou não.
+
+Elas funcionam bem para preparação de releases, filas editoriais, acompanhamentos de migração e qualquer checklist em que o progresso importa tanto quanto o conteúdo.
+
+## Sintaxe em Markdown
+
+```markdown
+- [ ] Escreva a página de visão geral
+- [x] Adicione exemplos localizados
+  - [ ] Revise as capturas de tela
+  - [x] Atualize os links internos
+```
+
+## Observações
+
+- Listas de tarefas seguem as mesmas regras de indentação das listas Markdown comuns.
+- Use `[ ]` para itens pendentes e `[x]` para itens concluídos.
+- Leitores da documentação publicada veem checkboxes estáticos e não podem alterná-los pela página.

package/src/pages/manual/content/blocks/task-lists.showcase.en-US.md

@@ -0,0 +1,23 @@
+## Showcase
+
+### Simple Tasks
+
+- [ ] Write the overview page
+- [x] Add the showcase page
+- [ ] Review internal links
+
+### Nested Tasks
+
+- [ ] Prepare the release
+  - [x] Update the changelog
+  - [ ] Run smoke tests
+  - [ ] Publish the package
+
+### Mixed Guidance
+
+> [!NOTE]
+> Readers can see the authored state of each task, but published checkboxes stay read-only.
+
+- [x] Keep completed items checked in the source.
+- [ ] Use task lists when the state matters more than the order.
+- Regular bullet lists are still better for collections that do not need a done/not-done signal.

package/src/pages/manual/content/blocks/task-lists.showcase.pt-BR.md

@@ -0,0 +1,23 @@
+## Showcase
+
+### Tarefas Simples
+
+- [ ] Escreva a página de visão geral
+- [x] Adicione a página de showcase
+- [ ] Revise os links internos
+
+### Tarefas Aninhadas
+
+- [ ] Prepare a release
+  - [x] Atualize o changelog
+  - [ ] Execute smoke tests
+  - [ ] Publique o pacote
+
+### Orientação de Uso
+
+> [!NOTE]
+> Leitores conseguem ver o estado definido no Markdown, mas os checkboxes publicados continuam somente leitura.
+
+- [x] Mantenha marcados os itens concluídos no conteúdo-fonte.
+- [ ] Use listas de tarefas quando o estado importar mais do que a ordem.
+- Listas com marcadores continuam melhores para coleções que não precisam de sinal de concluído ou pendente.

package/src/pages/manual.index.js

@@ -402,6 +402,34 @@ export default {
     }
   },
 
+  '/content/blocks/task-lists': {
+    config: {
+      icon: 'check_box',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Task lists — Documentation of Docsector Reader',
+          'pt-BR': 'Listas de tarefas — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'Task lists' },
+      'pt-BR': { title: 'Listas de tarefas' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'task list checklist checkbox todo done pending nested markdown gitbook',
+        'pt-BR': 'lista de tarefas checklist checkbox todo concluído pendente aninhada markdown gitbook'
+      }
+    }
+  },
+
   '/content/blocks/hints': {
     config: {
       icon: 'lightbulb',

package/src/pages/manual/components/d-subpage.overview.en-US.md

@@ -1,60 +0,0 @@
-## Overview
-
-`DSubpage` is a **convenience wrapper** that composes `DPage`, `DH1`, and `DPageSection` into a standard documentation page layout. It is the component loaded by the router for every subpage route.
-
-## How It Works
-
-DSubpage generates a deterministic numeric ID from the current route path using a hash function. This ID is passed to `DPageSection` to keep per-page renderer indexes stable across page navigations.
-
-## Template
-
-```html
-<d-page show-back-to-top-control>
-  <header>
-    <d-h1 :id="0" />
-  </header>
-  <main>
-    <d-page-section :id="id" />
-  </main>
-</d-page>
-```
-
-## ID Generation
-
-The `id` computed property creates a consistent hash from the route path:
-
-```javascript
-const id = computed(() => &#123;
-  const path = route.path
-  let hash = 5381
-  for (let i = 0; i < path.length; i++) &#123;
-    hash = (hash * 33) ^ path.charCodeAt(i)
-  &#125;
-  return hash >>> 0
-&#125;)
-```
-
-This keeps per-page renderer state isolated when switching between pages. Markdown section headings themselves use GitHub-compatible slugs derived from the heading text, so README-style Table of Contents links keep working.
-
-## When to Use
-
-DSubpage is automatically used by the router for all documentation pages. You don't need to use it directly unless creating custom page layouts. For standard documentation, the router handles everything:
-
-```javascript
-// In routes.js - this happens automatically
-&#123;
-  path: 'overview',
-  component: () => import('components/DSubpage.vue'),
-  meta: &#123; status: config.status &#125;
-&#125;
-```
-
-## Relationship with DPage
-
-- `DSubpage` **uses** `DPage` as its container
-- `DPage` handles layout (scroll, toolbar, drawer)
-- `DSubpage` handles content composition (H1 + sections)
-
-## Built-in Back to Top Control
-
-Routed documentation subpages enable DPage's floating back-to-top control automatically. The control is only shown when the content actually overflows, becomes visible after the reader scrolls a little, and visualizes the current reading progress with a circular indicator.

package/src/pages/manual/components/d-subpage.overview.pt-BR.md

@@ -1,60 +0,0 @@
-## Visão Geral
-
-`DSubpage` é um **wrapper de conveniência** que compõe `DPage`, `DH1` e `DPageSection` em um layout de página de documentação padrão. É o componente carregado pelo roteador para cada rota de sub-página.
-
-## Como Funciona
-
-DSubpage gera um ID numérico determinístico a partir do caminho da rota atual usando uma função hash. Esse ID é passado ao `DPageSection` para manter estáveis os índices internos do renderer em cada página.
-
-## Template
-
-```html
-<d-page show-back-to-top-control>
-  <header>
-    <d-h1 :id="0" />
-  </header>
-  <main>
-    <d-page-section :id="id" />
-  </main>
-</d-page>
-```
-
-## Geração de ID
-
-A propriedade computada `id` cria um hash consistente a partir do caminho da rota:
-
-```javascript
-const id = computed(() => &#123;
-  const path = route.path
-  let hash = 5381
-  for (let i = 0; i < path.length; i++) &#123;
-    hash = (hash * 33) ^ path.charCodeAt(i)
-  &#125;
-  return hash >>> 0
-&#125;)
-```
-
-Isso mantém o estado interno do renderer isolado ao navegar entre páginas. Os headings Markdown em si usam slugs compatíveis com GitHub derivados do texto do título, então links de Table of Contents no estilo README continuam funcionando.
-
-## Quando Usar
-
-DSubpage é usado automaticamente pelo roteador para todas as páginas de documentação. Você não precisa usá-lo diretamente, a menos que crie layouts de página customizados. Para documentação padrão, o roteador cuida de tudo:
-
-```javascript
-// Em routes.js - isso acontece automaticamente
-&#123;
-  path: 'overview',
-  component: () => import('components/DSubpage.vue'),
-  meta: &#123; status: config.status &#125;
-&#125;
-```
-
-## Relação com DPage
-
-- `DSubpage` **usa** `DPage` como container
-- `DPage` cuida do layout (scroll, toolbar, drawer)
-- `DSubpage` cuida da composição de conteúdo (H1 + seções)
-
-## Controle Integrado de Voltar ao Topo
-
-As sub-páginas de documentação roteadas habilitam automaticamente o controle flutuante de voltar ao topo do DPage. O controle só é exibido quando o conteúdo realmente tem overflow, fica visível após uma pequena rolagem do leitor e mostra o progresso atual de leitura com um indicador circular.