@docsector/docsector-reader 3.2.1 → 3.3.1

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/images.overview.en-US.md

@@ -2,15 +2,33 @@
 
 Use standard Markdown images to place screenshots, illustrations, diagrams, and product UI directly inside the reading flow.
 
+When an image appears on its own line, Docsector renders it as a block figure with click-to-zoom behavior.
+For plain Markdown images, the label is used as both the visible caption and the alt text, matching GitBook's block image model.
+
 ## Markdown Syntax
 
 ```markdown
 ![Dashboard overview](/images/example-dashboard.png)
 ```
 
+## Separate Alt Text And Caption
+
+Use raw HTML when the accessibility text and the visible caption should be different, or when you need `<picture>` / `<source>` for light and dark mode variants.
+
+```html
+<figure>
+	<picture>
+		<source srcset="/images/logo-dark.png" media="(prefers-color-scheme: dark)">
+		<img src="/images/logo-light.png" alt="Docsector Reader logo">
+	</picture>
+	<figcaption><p>Docsector Reader brand mark</p></figcaption>
+</figure>
+```
+
 ## Good Practices
 
-- Write descriptive alt text so the image still has meaning without the visual.
+- Write labels that still make sense without the visual, because plain Markdown uses the same text for caption and alt.
+- Use `<figure>` with `<figcaption>` when the visible caption should differ from the accessibility text.
 - Prefer absolute site paths such as `/images/...` for assets stored in `public/images/`.
 - Use screenshots to support the text, not replace the explanation.
-- When default Markdown syntax is not enough, raw HTML can be used for custom wrappers or sizing.
+- Click standalone block images to zoom; inline images that stay inside a paragraph remain on the inline path.

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

@@ -1,11 +1,19 @@
 ## Showcase
 
-### Basic Image
+### Markdown Image With Caption
 
 ![Docsector Reader logo](/images/logo.png)
 
+The label above is rendered as the visible caption and remains the image alt text.
+
 ### Image with Title
 
 ![Docsector Reader logo](/images/logo.png "Docsector Reader")
 
-The alt text remains part of the content model, so the page still communicates meaning if the image cannot be seen.
+The title attribute is preserved on the rendered image, while the block still keeps the same visible caption.
+
+### Raw HTML Figure With Separate Alt And Caption
+
+<figure><img src="/images/logo.png" alt="Docsector Reader brand mark"><figcaption><p>Docsector Reader logo used as a standalone brand image.</p></figcaption></figure>
+
+Click any standalone image block on this page to open the zoom view.

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',