@docsector/docsector-reader 3.2.2 → 3.3.1

package/README.md

@@ -71,6 +71,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 +618,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 +876,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 +1020,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.3.1'
 
 const HELP = `
   Docsector Reader v${VERSION}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.2.2",
+  "version": "3.3.1",
   "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/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>
@@ -94,6 +95,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

@@ -14,6 +14,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,
@@ -190,6 +191,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
@@ -469,10 +526,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
@@ -640,6 +706,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)
 

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.index.js

@@ -542,6 +542,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',