@docsector/docsector-reader 3.2.2 → 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
@@ -71,6 +72,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🔗 **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
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
 - 🗂️ **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
@@ -617,7 +619,7 @@ Docsector Reader works as a **rendering engine**: it provides the layout, compon
 │  ├── quasar.config.js      ← thin wrapper            │
 │  ├── src/pages/            ← Markdown + route defs    │
 │  ├── src/i18n/             ← language files + tags    │
-│  └── public/               ← logo, images, icons     │
+│  └── public/               ← logo, images, icons, files │
 │                                                       │
 │  ┌───────────────────────────────────────────────┐    │
 │  │  @docsector/docsector-reader (engine)         │    │
@@ -875,7 +877,8 @@ my-docs/
 └── public/
     ├── images/logo.png        # Project logo
     ├── flags/                 # Locale flag images
-    └── icons/                 # PWA icons
+    ├── icons/                 # PWA icons
+    └── files/                 # Downloadable attachments served as /files/...
 ```
 
   A common manual pattern is to keep core UI references under `src/pages/manual/basic/` with user-friendly page titles and focused entry pages such as Search, Branding, Version Switcher, Edit on GitHub, Translation Progress, and Previous & Next, end-user content references under `src/pages/manual/content/blocks/`, structural docs under `src/pages/manual/content/structures/`, and legacy/internal engine-specific references under `src/pages/manual/components/`.
@@ -1018,8 +1021,24 @@ Notes:
 Supported alert types: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`.
 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">
+Download the example file bundled with the docs.
+</d-file>
+```
+
+Notes:
+
+- Store small repo-tracked attachments in `public/files/` and link them with absolute paths such as `/files/manual/release-checklist.txt`.
+- `title` and `size` are optional. If `title` is omitted, the rendered card falls back to the filename from `src`.
+- The block body is rendered as an inline Markdown caption.
+- External URLs also work, so the same syntax can later point to R2 or another CDN without changing the page structure.
+
 ---
 
+
 ## 🖥️ CLI Commands
 
 ```bash

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.2.2",
+  "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/public/files/manual/release-checklist.txt

@@ -0,0 +1,7 @@
+Docsector Reader Release Checklist
+=================================
+
+1. Confirm the target route and page registry entry.
+2. Update the overview and showcase markdown pages.
+3. Run the focused test suite for the touched parser or helper.
+4. Run a production build and inspect the published artifact.

package/src/components/DPageFile.vue

@@ -0,0 +1,430 @@
+<script setup>
+import { computed, ref, watch } from 'vue'
+import { useQuasar } from 'quasar'
+import { useI18n } from 'vue-i18n'
+
+import { resolveFileIconUrl } from '../composables/useFileIcon'
+
+const BASE_URL = import.meta.env.BASE_URL || '/'
+
+defineOptions({
+  name: 'DPageFile'
+})
+
+const props = defineProps({
+  src: {
+    type: String,
+    default: ''
+  },
+  title: {
+    type: String,
+    default: ''
+  },
+  size: {
+    type: String,
+    default: ''
+  },
+  caption: {
+    type: String,
+    default: ''
+  }
+})
+
+const $q = useQuasar()
+const { t } = useI18n()
+const resolvedSize = ref(String(props.size || '').trim())
+
+const isExternal = computed(() => /^https?:\/\//i.test(props.src || ''))
+const resolvedHref = computed(() => {
+  const raw = String(props.src || '').trim()
+
+  if (!raw) {
+    return ''
+  }
+
+  if (/^(?:[a-z]+:)?\/\//i.test(raw) || /^(?:mailto:|tel:|data:)/i.test(raw)) {
+    return raw
+  }
+
+  const trimmedBase = String(BASE_URL).replace(/\/$/, '')
+
+  if (raw.startsWith('/')) {
+    return `${trimmedBase}${raw}` || raw
+  }
+
+  const normalized = raw.replace(/^\.\//, '')
+  return `${trimmedBase}/${normalized}`.replace(/\/+/g, '/')
+})
+const absoluteHref = computed(() => {
+  const href = resolvedHref.value
+
+  if (!href || /^(?:[a-z]+:)?\/\//i.test(href)) {
+    return href
+  }
+
+  if (typeof window === 'undefined') {
+    return href
+  }
+
+  return new URL(href, window.location.origin).toString()
+})
+const fileName = computed(() => {
+  const normalized = String(props.src || '')
+    .split('#')[0]
+    .split('?')[0]
+  const rawSegment = normalized
+    .split('/')
+    .filter(Boolean)
+    .pop() || ''
+
+  if (!rawSegment) {
+    return ''
+  }
+
+  try {
+    return decodeURIComponent(rawSegment)
+  } catch {
+    return rawSegment
+  }
+})
+const displayTitle = computed(() => {
+  return props.title || fileName.value || t('page.file.defaultTitle')
+})
+const displayHeading = computed(() => {
+  if (props.title && fileName.value && fileName.value !== props.title) {
+    return `${props.title} (${fileName.value})`
+  }
+
+  return displayTitle.value
+})
+const iconUrl = computed(() => {
+  return resolveFileIconUrl(fileName.value || displayTitle.value || props.src, {
+    preferLight: !$q.dark.isActive
+  })
+})
+
+const formatFileSize = (bytes) => {
+  const value = Number(bytes)
+
+  if (!Number.isFinite(value) || value <= 0) {
+    return ''
+  }
+
+  const units = ['B', 'KB', 'MB', 'GB', 'TB']
+  let size = value
+  let unitIndex = 0
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024
+    unitIndex++
+  }
+
+  const maximumFractionDigits = size >= 100 || unitIndex === 0 ? 0 : (size >= 10 ? 1 : 2)
+  return `${new Intl.NumberFormat(undefined, {
+    maximumFractionDigits,
+    minimumFractionDigits: 0
+  }).format(size)} ${units[unitIndex]}`
+}
+
+const readContentLength = async (href, options = {}) => {
+  const response = await fetch(href, options)
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`)
+  }
+
+  const contentLength = response.headers.get('content-length') || response.headers.get('Content-Length')
+  return formatFileSize(contentLength)
+}
+
+const hydrateSize = async () => {
+  const manualSize = String(props.size || '').trim()
+  resolvedSize.value = manualSize
+
+  if (manualSize || !absoluteHref.value || typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    const automaticSize = await readContentLength(absoluteHref.value, {
+      method: 'HEAD'
+    })
+
+    if (automaticSize) {
+      resolvedSize.value = automaticSize
+      return
+    }
+
+    if (!isExternal.value) {
+      const fallbackSize = await readContentLength(absoluteHref.value)
+      if (fallbackSize) {
+        resolvedSize.value = fallbackSize
+      }
+    }
+  } catch {
+    // External URLs may block access to Content-Length via CORS.
+  }
+}
+
+watch([
+  () => props.size,
+  absoluteHref
+], () => {
+  hydrateSize()
+}, {
+  immediate: true
+})
+
+const openFile = () => {
+  const href = absoluteHref.value
+
+  if (!href || typeof window === 'undefined') {
+    return
+  }
+
+  const link = document.createElement('a')
+
+  link.href = href
+  link.target = '_blank'
+  link.rel = 'noopener noreferrer'
+  document.body.appendChild(link)
+  link.click()
+  link.remove()
+}
+
+const downloadFile = async () => {
+  const href = absoluteHref.value
+
+  if (!href || typeof window === 'undefined') {
+    return
+  }
+
+  if (isExternal.value) {
+    openFile()
+    return
+  }
+
+  try {
+    const response = await fetch(href)
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`)
+    }
+
+    const blob = await response.blob()
+    const objectUrl = window.URL.createObjectURL(blob)
+    const link = document.createElement('a')
+
+    link.href = objectUrl
+    link.download = fileName.value || displayTitle.value || 'download'
+    link.rel = 'noopener noreferrer'
+    document.body.appendChild(link)
+    link.click()
+    link.remove()
+
+    window.setTimeout(() => {
+      window.URL.revokeObjectURL(objectUrl)
+    }, 1000)
+  } catch {
+    window.location.assign(href)
+  }
+}
+</script>
+
+<template>
+<div class="d-page-file">
+  <div class="d-page-file__body">
+    <div class="d-page-file__media-column">
+      <div class="d-page-file__media" aria-hidden="true">
+        <img
+          v-if="iconUrl"
+          class="d-page-file__icon"
+          :src="iconUrl"
+          alt=""
+          loading="lazy"
+        />
+        <q-icon
+          v-else
+          name="attach_file"
+          size="30px"
+        />
+      </div>
+
+      <div v-if="resolvedSize" class="d-page-file__size">{{ resolvedSize }}</div>
+    </div>
+
+    <div class="d-page-file__content">
+      <div class="d-page-file__title">{{ displayHeading }}</div>
+
+      <div
+        v-if="caption"
+        class="d-page-file__caption"
+        v-html="caption"
+      ></div>
+    </div>
+
+    <div class="d-page-file__actions">
+      <q-btn
+        no-caps
+        unelevated
+        padding="8px 12px"
+        class="d-page-file__action-button d-page-file__action-button--primary"
+        icon="download"
+        :label="t('page.file.download')"
+        @click="downloadFile"
+      />
+
+      <q-btn
+        no-caps
+        unelevated
+        padding="8px 12px"
+        class="d-page-file__action-button d-page-file__action-button--secondary"
+        icon="open_in_new"
+        :label="t('page.file.open')"
+        @click="openFile"
+      />
+    </div>
+  </div>
+</div>
+</template>
+
+<style lang="sass">
+body.body--light
+  --d-page-file-bg: linear-gradient(180deg, #faf8f2 0%, #ffffff 100%)
+  --d-page-file-border: rgba(101, 85, 41, 0.18)
+  --d-page-file-shadow: rgba(101, 85, 41, 0.08)
+  --d-page-file-media-bg: rgba(255, 255, 255, 0.82)
+  --d-page-file-media-border: rgba(101, 85, 41, 0.1)
+  --d-page-file-meta: #665f4f
+  --d-page-file-caption: #4d5563
+  --d-page-file-accent: #655529
+  --d-page-file-action-text: #4d4020
+  --d-page-file-action-border: rgba(101, 85, 41, 0.22)
+  --d-page-file-action-bg-hover: rgba(101, 85, 41, 0.06)
+
+body.body--dark
+  --d-page-file-bg: linear-gradient(180deg, rgba(255, 248, 235, 0.05) 0%, rgba(255, 255, 255, 0.02) 100%)
+  --d-page-file-border: rgba(255, 235, 194, 0.14)
+  --d-page-file-shadow: rgba(0, 0, 0, 0.28)
+  --d-page-file-media-bg: rgba(255, 255, 255, 0.94)
+  --d-page-file-media-border: rgba(255, 255, 255, 0.18)
+  --d-page-file-meta: rgba(255, 255, 255, 0.7)
+  --d-page-file-caption: rgba(255, 255, 255, 0.9)
+  --d-page-file-accent: #d7bc7e
+  --d-page-file-action-text: rgba(255, 255, 255, 0.92)
+  --d-page-file-action-border: rgba(255, 235, 194, 0.18)
+  --d-page-file-action-bg-hover: rgba(255, 235, 194, 0.08)
+
+.d-page-file
+  margin: 1.5rem 0
+  border: 1px solid var(--d-page-file-border)
+  border-radius: 18px
+  background: var(--d-page-file-bg)
+  box-shadow: 0 16px 36px var(--d-page-file-shadow)
+  overflow: hidden
+
+.d-page-file__body
+  display: flex
+  align-items: center
+  gap: 1rem
+  padding: 0.82rem 0.92rem
+
+.d-page-file__media-column
+  display: flex
+  flex: 0 0 68px
+  flex-direction: column
+  align-items: center
+  gap: 0.16rem
+
+.d-page-file__media
+  width: 56px
+  height: 56px
+  display: flex
+  align-items: center
+  justify-content: center
+  border-radius: 16px
+  background: var(--d-page-file-media-bg)
+  box-shadow: inset 0 0 0 1px var(--d-page-file-media-border)
+  color: var(--d-page-file-accent)
+
+.d-page-file__size
+  width: 100%
+  text-align: center
+  color: var(--d-page-file-meta)
+  font-size: 0.8rem
+  font-weight: 700
+  line-height: 1.05
+
+.d-page-file__icon
+  display: block
+  width: 32px
+  height: 32px
+
+.d-page-file__content
+  min-width: 0
+  flex: 1 1 auto
+
+.d-page-file__title
+  font-size: 1rem
+  font-weight: 700
+  line-height: 1.4
+  word-break: break-word
+
+.d-page-file__caption
+  margin-top: 0.35rem
+  color: var(--d-page-file-caption)
+
+  > :first-child
+    margin-top: 0
+
+  > :last-child
+    margin-bottom: 0
+
+.d-page-file__actions
+  display: flex
+  flex: 0 0 auto
+  align-items: center
+  gap: 0.6rem
+  align-self: center
+
+.d-page-file__action-button
+  min-height: 40px
+  border-radius: 10px
+  border: 1px solid var(--d-page-file-action-border)
+  background: transparent !important
+  color: var(--d-page-file-action-text) !important
+  transition: transform 0.18s ease, background-color 0.18s ease, border-color 0.18s ease
+
+  .q-btn__content
+    gap: 0.45rem
+    font-size: 0.9rem
+    font-weight: 600
+    line-height: 1
+
+  .q-focus-helper,
+  &:before,
+  &:after
+    display: none
+
+  &:hover
+    transform: translateY(-1px)
+    background: var(--d-page-file-action-bg-hover) !important
+
+  &:focus-visible
+    outline: 2px solid var(--d-page-file-accent)
+    outline-offset: 2px
+
+.d-page-file__action-button--primary
+  border-color: var(--d-page-file-action-border)
+
+@media (max-width: 720px)
+  .d-page-file__body
+    flex-wrap: wrap
+    align-items: flex-start
+
+  .d-page-file__actions
+    width: 100%
+
+  .d-page-file__action-button
+    flex: 1 1 0
+</style>

package/src/components/DPageTokens.vue

@@ -23,6 +23,7 @@ import DPageSourceCode from './DPageSourceCode.vue'
 import DMermaidDiagram from './DMermaidDiagram.vue'
 import DPageBlockquote from './DPageBlockquote.vue'
 import DPageImage from './DPageImage.vue'
+import DPageFile from './DPageFile.vue'
 import DQuickLinks from './DQuickLinks.vue'
 import DPageExpandable from './DPageExpandable.vue'
 </script>
@@ -57,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>
 
@@ -94,6 +97,14 @@ import DPageExpandable from './DPageExpandable.vue'
     <div v-html="token.content"></div>
   </d-page-blockquote>
 
+  <d-page-file
+    v-else-if="token.tag === 'file'"
+    :src="token.src"
+    :title="token.title"
+    :size="token.size"
+    :caption="token.caption"
+  />
+
   <d-page-source-code
     v-else-if="token.tag === 'code'"
     :index="id + token.codeIndex"

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([
@@ -14,6 +15,7 @@ const ALERT_MESSAGE_TYPES = new Set([
 
 const QUICK_LINKS_MARKER_PREFIX = '@@DOCSECTOR_QUICK_LINKS_'
 const EXPANDABLE_MARKER_PREFIX = '@@DOCSECTOR_EXPANDABLE_'
+const FILE_MARKER_PREFIX = '@@DOCSECTOR_FILE_'
 const CODE_SEGMENT_MARKER_PREFIX = '@@DOCSECTOR_CODE_SEGMENT_'
 const MATH_KATEX_OPTIONS = {
   throwOnError: false,
@@ -113,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
@@ -190,6 +218,62 @@ const extractExpandableBlocks = (source = '') => {
   }
 }
 
+const getFileTitleFromSrc = (src = '') => {
+  const normalized = String(src)
+    .split('#')[0]
+    .split('?')[0]
+  const rawSegment = normalized
+    .split('/')
+    .filter(Boolean)
+    .pop() || ''
+
+  if (!rawSegment) {
+    return 'Download file'
+  }
+
+  try {
+    return decodeURIComponent(rawSegment)
+  } catch {
+    return rawSegment
+  }
+}
+
+const extractFileBlocks = (source = '') => {
+  const map = new Map()
+  let index = 0
+
+  const replaceBlock = (match, rawAttrs, rawCaption = '') => {
+    const attrs = parseCustomTagAttributes(rawAttrs)
+    const src = decodeHtmlEntities(attrs.src || attrs.href || '').trim()
+
+    if (!src) {
+      return match
+    }
+
+    const marker = `${FILE_MARKER_PREFIX}${index}@@`
+    index++
+
+    map.set(marker, {
+      src,
+      title: decodeHtmlEntities(attrs.title || attrs.name || '').trim(),
+      size: decodeHtmlEntities(attrs.size || '').trim(),
+      caption: String(rawCaption).trim()
+    })
+
+    return `\n${marker}\n`
+  }
+
+  const replacedSelfClosing = String(source).replace(/<d-file\b([^>]*)\/\s*>/gi, (match, rawAttrs) => {
+    return replaceBlock(match, rawAttrs)
+  })
+  const replaced = replacedSelfClosing.replace(/<d-file\b([^>]*)>([\s\S]*?)<\/d-file>/gi, replaceBlock)
+
+  return {
+    source: replaced,
+    fileMap: map
+  }
+}
+
 const parseFenceAttributes = (raw = '') => {
   const parsed = {}
   const pattern = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s;]+))/g
@@ -411,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
@@ -421,6 +513,11 @@ const createMarkdownBlockParser = () => {
     rightDelimiter: ';',
     allowedAttributes: ['filename', 'group', 'tab', 'breadcrumb']
   })
+  markdown.use(taskLists, {
+    enabled: false,
+    label: false,
+    labelAfter: false
+  })
 
   return markdown
 }
@@ -469,10 +566,19 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
   })
 
   const { source: sourceWithQuickLinks, quickLinksMap } = extractQuickLinksBlocks(sourceWithExpandables)
+  const { source: sourceWithFiles, fileMap } = extractFileBlocks(sourceWithQuickLinks)
+
+  fileMap.forEach((data, marker) => {
+    fileMap.set(marker, {
+      ...data,
+      caption: restoreShieldedCodeSegments(data.caption, codeSegmentsMap)
+    })
+  })
+
   const markdown = createMarkdownBlockParser()
   const markdownInline = createMarkdownInlineParser()
   const markdownEnv = {}
-  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithQuickLinks, codeSegmentsMap), markdownEnv)
+  const parsed = markdown.parse(restoreShieldedCodeSegments(sourceWithFiles, codeSegmentsMap), markdownEnv)
   const tokens = []
 
   let level = 0
@@ -596,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) {
@@ -640,6 +746,22 @@ export const tokenizePageSectionSource = (source = '', options = {}) => {
             break
           }
 
+          if (fileMap.has(element.content.trim())) {
+            const data = fileMap.get(element.content.trim())
+
+            tokens.push({
+              tag: 'file',
+              map: element.map,
+              src: data.src,
+              title: data.title || getFileTitleFromSrc(data.src),
+              size: data.size,
+              caption: data.caption !== ''
+                ? markdownInline.renderInline(data.caption, markdownEnv)
+                : ''
+            })
+            break
+          }
+
           if (tag === 'p') {
             const imageToken = parseStandaloneImageToken(element.content)
 
@@ -697,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
 
@@ -729,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/i18n/languages/en-US.hjson

@@ -38,6 +38,13 @@
     copied: 'Copied!',
     viewAsMarkdown: 'View as Markdown',
     viewAsMarkdownCaption: 'View this page as plain text',
+    file: {
+      label: 'File',
+      defaultTitle: 'Download file',
+      external: 'External file',
+      download: 'Download',
+      open: 'Open'
+    },
     openInChatGPT: 'Open in ChatGPT',
     openInChatGPTCaption: 'Ask ChatGPT about this page',
     openInClaude: 'Open in Claude',

package/src/i18n/languages/pt-BR.hjson

@@ -37,6 +37,13 @@
     copied: 'Copiado!',
     viewAsMarkdown: 'Ver como Markdown',
     viewAsMarkdownCaption: 'Ver esta página como texto simples',
+    file: {
+      label: 'Arquivo',
+      defaultTitle: 'Baixar arquivo',
+      external: 'Arquivo externo',
+      download: 'Baixar',
+      open: 'Abrir'
+    },
     openInChatGPT: 'Abrir no ChatGPT',
     openInChatGPTCaption: 'Pergunte ao ChatGPT sobre esta página',
     openInClaude: 'Abrir no Claude',

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

@@ -45,7 +45,7 @@ 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/)
+- [Images](/manual/content/blocks/images/overview/), [Files](/manual/content/blocks/files/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
 
@@ -132,6 +132,20 @@ Set `open="true"` when the block should start expanded.
 
 The expandable body supports paragraphs, lists, alerts, code blocks, Mermaid diagrams, tables, raw HTML, and quick links. Keep headings outside the expandable block in this first version, because headings inside the body are flattened to regular paragraphs to preserve the page ToC.
 
+### File Blocks
+
+Use `<d-file>` to publish downloadable attachments from repo-tracked files or external storage without leaving Markdown:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+Download the example attachment used in this manual.
+</d-file>
+```
+
+Store repo-tracked files under `public/files/` and prefer absolute site paths such as `/files/...`.
+
+`title` and `size` are optional. When `title` is omitted, the UI falls back to the file name from `src`. The caption body supports inline Markdown, and the same syntax also works with external URLs if you later move storage to R2 or another CDN.
+
 ## Adding a New Language
 
 1. Create `src/i18n/languages/xx-XX.hjson` with all UI translations

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

@@ -45,7 +45,7 @@ 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/)
+- [Imagens](/manual/content/blocks/images/overview/), [Arquivos](/manual/content/blocks/files/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
 
@@ -132,6 +132,20 @@ Defina `open="true"` quando o bloco precisar começar aberto.
 
 O corpo do expansível suporta parágrafos, listas, alertas, blocos de código, diagramas Mermaid, tabelas, HTML bruto e quick links. Nesta primeira versão, mantenha títulos fora do bloco expansível, porque títulos dentro do corpo viram parágrafos comuns para preservar o ToC da página.
 
+### Blocos de Arquivo
+
+Use `<d-file>` para publicar anexos baixáveis a partir de arquivos versionados no repositório ou de storage externo sem sair do Markdown:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
+Baixe o anexo de exemplo usado neste manual.
+</d-file>
+```
+
+Guarde arquivos versionados no repositório em `public/files/` e prefira caminhos absolutos do site, como `/files/...`.
+
+`title` e `size` são opcionais. Quando `title` não é informado, a UI usa o nome do arquivo presente em `src`. O corpo do bloco funciona como legenda com Markdown inline, e a mesma sintaxe também aceita URLs externas caso você mova o storage para R2 ou outro CDN no futuro.
+
 ## Adicionando um Novo Idioma
 
 1. Crie `src/i18n/languages/xx-XX.hjson` com todas as traduções de UI

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

@@ -0,0 +1,27 @@
+## Overview
+
+Files render a download card directly inside Markdown so a page or subpage can publish attachments without leaving the normal authoring flow.
+
+They are useful for checklists, sample bundles, PDFs, release notes, and any other file that should be linked from the reading flow.
+
+## Markdown Syntax
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+Download the example attachment used in this manual.
+</d-file>
+```
+
+You can also omit the caption body when the file name already provides enough context:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" size="1 KB" />
+```
+
+## Notes
+
+- Store small repo-tracked attachments under `public/files/` and prefer absolute paths such as `/files/...`.
+- `src` is required. `title` and `size` are optional.
+- When `title` is omitted, the rendered card falls back to the file name from `src`.
+- The block body is rendered as an inline Markdown caption.
+- External URLs also work, so the same syntax can point to a future R2 bucket or another CDN.

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

@@ -0,0 +1,27 @@
+## Visão Geral
+
+Arquivos renderizam um card de download diretamente no Markdown para que uma page ou subpage publique anexos sem sair do fluxo normal de autoria.
+
+Eles são úteis para checklists, bundles de exemplo, PDFs, notas de release e qualquer outro arquivo que precise ficar no fluxo de leitura.
+
+## Sintaxe em Markdown
+
+```html
+<d-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
+Baixe o anexo de exemplo usado neste manual.
+</d-file>
+```
+
+Você também pode omitir o corpo da legenda quando o nome do arquivo já fornece contexto suficiente:
+
+```html
+<d-file src="/files/manual/release-checklist.txt" size="1 KB" />
+```
+
+## Observações
+
+- Guarde anexos pequenos versionados no repositório em `public/files/` e prefira caminhos absolutos como `/files/...`.
+- `src` é obrigatório. `title` e `size` são opcionais.
+- Quando `title` não é informado, o card renderizado usa o nome do arquivo presente em `src`.
+- O corpo do bloco é renderizado como legenda com Markdown inline.
+- URLs externas também funcionam, então a mesma sintaxe pode apontar no futuro para um bucket R2 ou outro CDN.

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

@@ -0,0 +1,17 @@
+## Showcase
+
+### Local File with Caption
+
+<d-file src="/files/manual/release-checklist.txt" title="Release checklist" size="1 KB">
+Download the example checklist published from `public/files/manual`.
+</d-file>
+
+### Local File with Automatic Size
+
+<d-file src="/files/manual/release-checklist.txt" />
+
+### External File URL
+
+<d-file src="https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" title="Reference PDF" size="13 KB">
+The same block can point to a CDN or object storage URL without changing the page layout.
+</d-file>

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

@@ -0,0 +1,17 @@
+## Demonstração
+
+### Arquivo Local com Legenda
+
+<d-file src="/files/manual/release-checklist.txt" title="Checklist de release" size="1 KB">
+Baixe o checklist de exemplo publicado a partir de `public/files/manual`.
+</d-file>
+
+### Arquivo Local com Tamanho Automático
+
+<d-file src="/files/manual/release-checklist.txt" />
+
+### URL Externa de Arquivo
+
+<d-file src="https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" title="PDF de referência" size="13 KB">
+O mesmo bloco pode apontar para um CDN ou URL de object storage sem mudar o layout da página.
+</d-file>

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',
@@ -542,6 +570,35 @@ export default {
     }
   },
 
+  '/content/blocks/files': {
+    config: {
+      icon: 'attach_file',
+      status: 'new',
+      version: 'v3.3.0',
+      meta: {
+        description: {
+          'en-US': 'Files — Documentation of Docsector Reader',
+          'pt-BR': 'Arquivos — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'Files' },
+      'pt-BR': { title: 'Arquivos' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'files download attachments markdown assets public r2 cloudflare github',
+        'pt-BR': 'arquivos download anexos markdown assets public r2 cloudflare github'
+      }
+    }
+  },
+
   '/content/blocks/math-and-tex': {
     config: {
       icon: 'functions',

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.