@docsector/docsector-reader 3.4.0 → 3.6.0

package/README.md

@@ -73,7 +73,9 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🧬 **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
+- 🌐 **Embedded URL Blocks** — Use `<d-embedded-url url="https://...">...</d-embedded-url>` to render curated embeds for YouTube, Vimeo, Spotify, and CodePen with a safe link-card fallback for unsupported URLs
 - 🧭 **Quick Links Custom Element** — Use `<d-quick-links>` and `<d-quick-link>` in Markdown to render rich home navigation cards
+- 🗂️ **Cards Custom Element** — Use `<d-block-cards>` and `<d-block-card>` in Markdown to render linked content cards with optional cover images
 - 🗂️ **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
 - 🏷️ **Version Selector Badges** — Every version in the sidebar selector displays a color-coded badge: green for released, orange for draft, red for deprecated; fully customizable via `badge: { label, color, textColor }`
@@ -1036,6 +1038,21 @@ Notes:
 - 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.
 
+### Embedded URL Blocks
+
+```html
+<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube player demo">
+Optional caption rendered as inline Markdown.
+</d-embedded-url>
+```
+
+Notes:
+
+- Supported providers currently include YouTube, Vimeo, Spotify, and CodePen.
+- The block preserves the original query string, so provider options such as `autoplay=1&loop=1` keep working when supported by the destination service.
+- Unsupported or private URLs fall back to a safe external-link card instead of attempting a generic iframe.
+- Raw HTML remains the escape hatch when you need a provider outside the curated list or full manual iframe control.
+
 ---
 
 

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

package/jsconfig.json

@@ -13,5 +13,5 @@
       "stores/*": ["src/stores/*"]
     }
   },
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "tmp"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "3.4.0",
+  "version": "3.6.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",

package/public/images/cards/getting-started-cover.svg

@@ -0,0 +1,60 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" role="img" aria-labelledby="title desc">
+  <title id="title">Getting started cover</title>
+  <desc id="desc">Abstract cover with warm gradients and onboarding steps.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#12141c"/>
+      <stop offset="48%" stop-color="#1b2230"/>
+      <stop offset="100%" stop-color="#27384d"/>
+    </linearGradient>
+    <linearGradient id="panel" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#f1d8a1" stop-opacity="0.95"/>
+      <stop offset="100%" stop-color="#b78f41" stop-opacity="0.85"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#69d8c3"/>
+      <stop offset="100%" stop-color="#8ab6ff"/>
+    </linearGradient>
+    <filter id="blur" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="24"/>
+    </filter>
+  </defs>
+
+  <rect width="1280" height="720" fill="url(#bg)"/>
+  <circle cx="1120" cy="132" r="136" fill="#69d8c3" opacity="0.16" filter="url(#blur)"/>
+  <circle cx="180" cy="640" r="170" fill="#8ab6ff" opacity="0.18" filter="url(#blur)"/>
+
+  <rect x="90" y="96" width="470" height="528" rx="34" fill="#0f141c" opacity="0.92" stroke="#3a4c63"/>
+  <rect x="126" y="140" width="398" height="18" rx="9" fill="url(#accent)" opacity="0.9"/>
+  <rect x="126" y="188" width="182" height="28" rx="14" fill="#f5efe1" opacity="0.92"/>
+  <rect x="126" y="242" width="300" height="16" rx="8" fill="#8da6c7" opacity="0.7"/>
+  <rect x="126" y="272" width="260" height="16" rx="8" fill="#8da6c7" opacity="0.55"/>
+
+  <g transform="translate(126 344)">
+    <rect width="318" height="68" rx="18" fill="#17212d" stroke="#32465d"/>
+    <circle cx="36" cy="34" r="15" fill="#69d8c3"/>
+    <path d="M29 34l5 5 10-12" fill="none" stroke="#0d1722" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+    <rect x="72" y="22" width="110" height="12" rx="6" fill="#f1f5f9"/>
+    <rect x="72" y="42" width="160" height="10" rx="5" fill="#8da6c7" opacity="0.75"/>
+  </g>
+
+  <g transform="translate(126 430)">
+    <rect width="356" height="68" rx="18" fill="#17212d" stroke="#32465d"/>
+    <circle cx="36" cy="34" r="15" fill="#69d8c3" opacity="0.82"/>
+    <path d="M29 34l5 5 10-12" fill="none" stroke="#0d1722" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+    <rect x="72" y="22" width="132" height="12" rx="6" fill="#f1f5f9"/>
+    <rect x="72" y="42" width="200" height="10" rx="5" fill="#8da6c7" opacity="0.75"/>
+  </g>
+
+  <g transform="translate(640 88)">
+    <rect width="548" height="548" rx="44" fill="url(#panel)"/>
+    <rect x="78" y="84" width="392" height="244" rx="26" fill="#0f141c" opacity="0.92"/>
+    <path d="M128 282c42-72 86-108 132-108 35 0 69 15 103 44 31 27 58 40 80 40 39 0 73-21 104-64l29 20c-42 63-87 94-136 94-33 0-67-13-102-39-32-24-60-36-84-36-34 0-67 28-98 84z" fill="#69d8c3"/>
+    <circle cx="272" cy="206" r="46" fill="#8ab6ff" opacity="0.92"/>
+    <rect x="78" y="372" width="188" height="22" rx="11" fill="#0f141c" opacity="0.88"/>
+    <rect x="78" y="414" width="300" height="16" rx="8" fill="#243447" opacity="0.6"/>
+    <rect x="78" y="444" width="262" height="16" rx="8" fill="#243447" opacity="0.44"/>
+    <rect x="78" y="484" width="164" height="56" rx="18" fill="#0f141c" opacity="0.88"/>
+    <rect x="102" y="506" width="114" height="12" rx="6" fill="#f5efe1" opacity="0.88"/>
+  </g>
+</svg>

package/public/images/cards/quick-links-cover.svg

@@ -0,0 +1,71 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" role="img" aria-labelledby="title desc">
+  <title id="title">Quick links cover</title>
+  <desc id="desc">Abstract navigation cover with cards and directional accents.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#10261f"/>
+      <stop offset="45%" stop-color="#16372d"/>
+      <stop offset="100%" stop-color="#1e4d3e"/>
+    </linearGradient>
+    <linearGradient id="card" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#f3f0e7"/>
+      <stop offset="100%" stop-color="#d5ddd1"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#69d8c3"/>
+      <stop offset="100%" stop-color="#d3b874"/>
+    </linearGradient>
+    <filter id="blur" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="26"/>
+    </filter>
+  </defs>
+
+  <rect width="1280" height="720" fill="url(#bg)"/>
+  <circle cx="154" cy="138" r="126" fill="#69d8c3" opacity="0.18" filter="url(#blur)"/>
+  <circle cx="1090" cy="598" r="170" fill="#d3b874" opacity="0.16" filter="url(#blur)"/>
+
+  <g transform="translate(98 112)">
+    <rect width="452" height="480" rx="42" fill="#0f1714" opacity="0.94" stroke="#385247"/>
+    <rect x="44" y="48" width="162" height="18" rx="9" fill="url(#accent)"/>
+    <rect x="44" y="100" width="278" height="18" rx="9" fill="#f3f0e7" opacity="0.94"/>
+    <rect x="44" y="136" width="212" height="14" rx="7" fill="#9cb5ac" opacity="0.58"/>
+
+    <g transform="translate(44 204)">
+      <rect width="364" height="86" rx="24" fill="#17231e" stroke="#33493f"/>
+      <rect x="28" y="24" width="116" height="12" rx="6" fill="#f3f0e7"/>
+      <rect x="28" y="46" width="176" height="10" rx="5" fill="#8aa196" opacity="0.82"/>
+      <circle cx="320" cy="43" r="20" fill="#22362d"/>
+      <path d="M311 43h18M321 34l9 9-9 9" fill="none" stroke="#69d8c3" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+
+    <g transform="translate(44 310)">
+      <rect width="330" height="86" rx="24" fill="#17231e" stroke="#33493f"/>
+      <rect x="28" y="24" width="96" height="12" rx="6" fill="#f3f0e7"/>
+      <rect x="28" y="46" width="156" height="10" rx="5" fill="#8aa196" opacity="0.82"/>
+      <circle cx="286" cy="43" r="20" fill="#22362d"/>
+      <path d="M277 43h18M287 34l9 9-9 9" fill="none" stroke="#69d8c3" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+  </g>
+
+  <g transform="translate(646 100)">
+    <rect width="536" height="520" rx="44" fill="url(#card)" opacity="0.98"/>
+    <rect x="58" y="56" width="420" height="248" rx="28" fill="#0f1714" opacity="0.94"/>
+    <g transform="translate(110 114)">
+      <rect width="116" height="116" rx="28" fill="#69d8c3"/>
+      <path d="M40 58h36M58 40l18 18-18 18" fill="none" stroke="#0f1714" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+    <g transform="translate(250 114)">
+      <rect width="116" height="116" rx="28" fill="#d3b874"/>
+      <path d="M40 58h36M58 40l18 18-18 18" fill="none" stroke="#0f1714" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+    <g transform="translate(180 272)">
+      <rect width="116" height="116" rx="28" fill="#8ab6ff"/>
+      <path d="M40 58h36M58 40l18 18-18 18" fill="none" stroke="#0f1714" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    </g>
+    <rect x="58" y="360" width="204" height="18" rx="9" fill="#10261f" opacity="0.92"/>
+    <rect x="58" y="396" width="294" height="14" rx="7" fill="#425b52" opacity="0.6"/>
+    <rect x="58" y="424" width="248" height="14" rx="7" fill="#425b52" opacity="0.42"/>
+    <rect x="58" y="470" width="172" height="58" rx="18" fill="#10261f" opacity="0.92"/>
+    <rect x="84" y="493" width="120" height="12" rx="6" fill="#f3f0e7" opacity="0.92"/>
+  </g>
+</svg>

package/src/components/DBlockCard.vue

@@ -0,0 +1,223 @@
+<script setup>
+const BASE_URL = import.meta.env.BASE_URL || '/'
+
+defineOptions({
+  name: 'DBlockCard'
+})
+
+const props = defineProps({
+  items: {
+    type: Array,
+    default: () => []
+  },
+  title: {
+    type: String,
+    default: ''
+  }
+})
+
+const isExternal = (item) => {
+  const href = item?.href || ''
+  return /^https?:\/\//i.test(href)
+}
+
+const itemTag = (item) => {
+  if (item?.to) return 'router-link'
+  return 'a'
+}
+
+const itemProps = (item) => {
+  if (item?.to) {
+    return {
+      to: item.to
+    }
+  }
+
+  const href = item?.href || ''
+  return {
+    href,
+    target: isExternal(item) ? '_blank' : undefined,
+    rel: isExternal(item) ? 'noopener noreferrer' : undefined
+  }
+}
+
+const resolveAssetUrl = (raw = '') => {
+  const value = String(raw || '').trim()
+
+  if (!value) {
+    return ''
+  }
+
+  if (/^(?:[a-z]+:)?\/\//i.test(value) || /^(?:data:|blob:)/i.test(value)) {
+    return value
+  }
+
+  const trimmedBase = String(BASE_URL).replace(/\/$/, '')
+
+  if (value.startsWith('/')) {
+    return `${trimmedBase}${value}` || value
+  }
+
+  const normalized = value.replace(/^\.\//, '')
+  return `${trimmedBase}/${normalized}`.replace(/\/+/g, '/')
+}
+</script>
+
+<template>
+<div class="d-cards">
+  <h3 v-if="title" class="d-cards__title">{{ title }}</h3>
+
+  <div class="d-cards__grid">
+    <component
+      :is="itemTag(item)"
+      v-for="(item, index) in props.items"
+      :key="`${item.title}-${index}`"
+      class="d-cards__link"
+      v-bind="itemProps(item)"
+    >
+      <q-card flat bordered class="d-cards__card">
+        <q-img
+          v-if="item.image"
+          :src="resolveAssetUrl(item.image)"
+          :alt="item.title"
+          ratio="1.7778"
+          class="d-cards__image"
+        />
+
+        <q-card-section v-else-if="item.icon" class="d-cards__icon-section">
+          <div class="d-cards__icon-surface">
+            <q-icon :name="item.icon" size="56px" color="primary" />
+          </div>
+        </q-card-section>
+
+        <q-card-section class="d-cards__body">
+          <div class="d-cards__heading-row">
+            <div class="d-cards__heading-group">
+              <q-icon
+                v-if="item.image && item.icon"
+                :name="item.icon"
+                size="18px"
+                color="primary"
+              />
+              <div class="d-cards__label">{{ item.title }}</div>
+            </div>
+
+            <q-icon :name="isExternal(item) ? 'arrow_outward' : 'arrow_forward'" size="18px" />
+          </div>
+
+          <div class="d-cards__description">{{ item.description }}</div>
+        </q-card-section>
+      </q-card>
+    </component>
+  </div>
+</div>
+</template>
+
+<style lang="sass">
+body.body--light
+  --d-cards-card-bg: #fffdf8
+  --d-cards-card-border: rgba(123, 94, 45, 0.16)
+  --d-cards-card-shadow: rgba(94, 73, 37, 0.08)
+  --d-cards-card-shadow-hover: rgba(94, 73, 37, 0.16)
+  --d-cards-description: #4d5563
+  --d-cards-icon-surface: linear-gradient(180deg, rgba(210, 190, 145, 0.22), rgba(210, 190, 145, 0.08))
+
+body.body--dark
+  --d-cards-card-bg: rgba(255, 248, 235, 0.035)
+  --d-cards-card-border: rgba(255, 235, 194, 0.12)
+  --d-cards-card-shadow: rgba(0, 0, 0, 0.25)
+  --d-cards-card-shadow-hover: rgba(0, 0, 0, 0.38)
+  --d-cards-description: rgba(255, 255, 255, 0.82)
+  --d-cards-icon-surface: linear-gradient(180deg, rgba(193, 166, 103, 0.18), rgba(193, 166, 103, 0.05))
+
+.d-cards
+  margin: 0 auto
+
+.d-cards__title
+  text-align: center
+  margin: 0 0 16px
+
+.d-cards__grid
+  display: grid
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr))
+  gap: 16px
+
+.d-cards__link
+  display: block
+  color: inherit
+  text-decoration: none
+  border-bottom: 0 !important
+  background: transparent !important
+
+.d-cards__link:hover,
+.d-cards__link:focus-visible,
+.d-cards__link:active,
+.d-cards__link:visited
+  color: inherit !important
+  text-decoration: none
+  border-bottom: 0 !important
+  background: transparent !important
+
+.d-cards__card
+  height: 100%
+  overflow: hidden
+  border-radius: 18px
+  background: var(--d-cards-card-bg)
+  border-color: var(--d-cards-card-border)
+  box-shadow: 0 12px 28px var(--d-cards-card-shadow)
+  transition: transform 180ms ease, box-shadow 180ms ease, border-color 180ms ease
+
+.d-cards__link:hover .d-cards__card,
+.d-cards__link:focus-visible .d-cards__card
+  transform: translateY(-2px)
+  box-shadow: 0 18px 36px var(--d-cards-card-shadow-hover)
+
+.d-cards__link:focus-visible
+  outline: none
+
+.d-cards__image
+  background: rgba(0, 0, 0, 0.05)
+
+.d-cards__icon-section
+  display: flex
+  padding-bottom: 0
+
+.d-cards__icon-surface
+  display: flex
+  align-items: center
+  justify-content: center
+  width: 100%
+  min-height: 156px
+  border-radius: 14px
+  background: var(--d-cards-icon-surface)
+
+.d-cards__body
+  display: grid
+  gap: 10px
+
+.d-cards__heading-row
+  display: flex
+  align-items: flex-start
+  justify-content: space-between
+  gap: 12px
+
+.d-cards__heading-group
+  display: flex
+  align-items: center
+  gap: 8px
+  min-width: 0
+
+.d-cards__label
+  font-size: 1rem
+  font-weight: 700
+  line-height: 1.35
+
+.d-cards__description
+  color: var(--d-cards-description)
+  font-size: 0.97rem
+  line-height: 1.55
+
+@media (max-width: 599px)
+  .d-cards__grid
+    grid-template-columns: 1fr
+</style>