@sewadah/selaras-docs 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## v1.3.0
+
+[compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.2.4...selaras-docs-v1.3.0)
+
+### 🚀 Enhancements
+
+- **feat(docs):** add logo to footer attribution ([1af91a6](https://github.com/sewadahapp/selaras/commit/1af91a6b66ac279255a0a6ca421dda89ee6c966e))
+- **feat(docs):** add contextual page contribution actions ([4e21d84](https://github.com/sewadahapp/selaras/commit/4e21d843dc514d6f6f50f0922371fe0cbf94a9c7))
+
+### 🩹 Fixes
+
+- **fix(docs):** render an empty state for blank Markdown pages ([bf4cb17](https://github.com/sewadahapp/selaras/commit/bf4cb1746311c10ff389e997aaec867b60fd9a83))
+- **fix(docs):** provide an optional theme picker fallback ([3ba8c5d](https://github.com/sewadahapp/selaras/commit/3ba8c5d2d24d45bab98fdae8163de0338ed11d7c))
+- **fix(docs):** align and refine footer layout ([029956a](https://github.com/sewadahapp/selaras/commit/029956a79b11b6d13610348a3f1bec516036dacb))
+
+Published against `@sewadah/selaras` ^0.9.0.
+
+## v1.2.4
+
+[compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.2.3...selaras-docs-v1.2.4)
+
+### 🚀 Enhancements
+
+- **feat(docs):** add interactive application blocks ([102ee68](https://github.com/sewadahapp/selaras/commit/102ee68bef82d12b07dc4788dc8ea2378435e0ea))
+- **feat(docs):** add error pages and local recovery boundaries ([371ed7a](https://github.com/sewadahapp/selaras/commit/371ed7a4fd873fa7e4647ab0b89b85dc0bb7a4b7))
+- **feat(docs):** add SEO metadata and static sharing images ([f6ec141](https://github.com/sewadahapp/selaras/commit/f6ec14152def06f91a62292b53ae2df50813b1d5))
+- **feat(docs):** add Seirama branding and design kit ([9fd9f19](https://github.com/sewadahapp/selaras/commit/9fd9f1948feaa19897ae24e982d33099d50a732c))
+- **feat(forms):** add leading and trailing content slots ([ebd0948](https://github.com/sewadahapp/selaras/commit/ebd094813a274d444319cb0354387c770ab8a6ef))
+
+### 🩹 Fixes
+
+- **fix(docs):** configure custom domain deployment ([b65908a](https://github.com/sewadahapp/selaras/commit/b65908a7aa4ad0d0b67029b41c338633e9faa50d))
+
+Published against `@sewadah/selaras` ^0.9.0.
+
 ## v1.2.3
 
 [compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.2.2...selaras-docs-v1.2.3)

package/README.md

@@ -57,6 +57,7 @@ export default defineAppConfig({
     repository: {
       url: 'https://github.com/example/project',
       editLinks: true,
+      issueLinks: true,
     },
     header: {
       search: true,
@@ -100,12 +101,35 @@ navBadges:
 Use `navigation: false` in a page's frontmatter to omit it from navigation, or
 set `navigation` to an object to override its navigation `title`, `icon`,
 `order`, and `navBadges`. Page frontmatter can also set `toc: false`,
-`aside: false`, `editLink: false`, or `prevNext: false` to hide those parts of
+`aside: false`, `editLink: false`, `issueLink: false`, or `prevNext: false` to hide those parts of
 the page shell. The sidebar also accepts an app-wide `collapsed` default; a
 folder's `collapse` value takes precedence. `main.fluid` expands the
 content width, `main.padded: false` removes its outer inset, and `header.fluid`
 and `footer.fluid` allow those regions to span the viewport.
 
+### Page actions
+
+With `repository.url` configured, **Edit this page** and **Report an issue**
+appear below the table of contents on desktop. On smaller screens, or when
+the page has no table of contents, they appear after the article and before
+Previous/Next navigation. Pages without an aside use the available content width.
+
+Set `repository.branch` and `repository.contentDirectory` to the branch and
+Markdown directory in your repository; their defaults are `main` and `content`.
+Generated issue links include the page title and route in a new issue draft.
+The links open the repository in a new tab; they do not submit changes or issues.
+
+Use `repository.editLinks: false` or `repository.issueLinks: false` to hide an
+action site-wide. Set `editLink: false` or `issueLink: false` in frontmatter to
+hide it on one page. GitHub and GitLab URLs are recognized automatically;
+set `repository.issueUrl` to use a different issue tracker or an issue-template
+chooser. Custom issue URLs are used unchanged. With no supported repository or
+custom issue URL, unavailable actions are omitted.
+
+Override `components/DocsPageActions.vue` to replace the group, or
+`components/DocsEditLink.vue` to customize the edit link. The
+`DocsTableOfContents` default slot renders content below its heading links.
+
 Create an application component with the same name as a layer component, such
 as `components/DocsHeader.vue`, to replace that part of the shell. Smaller
 pieces can be replaced on their own:
@@ -114,11 +138,91 @@ pieces can be replaced on their own:
 | --- | --- | --- |
 | `DocsHeaderBrand` | The header's home link content | `site.logo` and the site name |
 | `DocsFooterBrand` | The start of the footer | `footer.text` |
+| `DocsThemePicker` | Optional header theme control | Empty; provide your own component and set `header.themePicker: true` |
 | `DocsLogo` | The logo image, used by `DocsHeaderBrand` | `site.logo`, switching light/dark; size it with `--selaras-docs-logo-height` |
 
 For example, a `components/DocsFooterBrand.vue` containing `<DocsLogo />` adds
 the logo to the footer while leaving the header as configured.
 
+The layer does not include the Selaras site's theme presets. To offer your own
+themes, create `components/DocsThemePicker.vue` and enable
+`selarasDocs.header.themePicker` in `app.config.ts`. The layer's empty default
+keeps the header valid when the consuming site does not supply a picker.
+
+## Error recovery
+
+An existing Markdown file with no body content renders a **No content yet**
+view inside the documentation shell, with a themed vector illustration and a
+link back to the documentation. Zero-byte, whitespace-only and frontmatter-only
+pages remain valid pages rather than 404s. Header, navigation, configured page
+actions and Previous/Next remain available. Adding body content replaces the
+empty view automatically.
+
+Set `selarasDocs.empty.title` and `selarasDocs.empty.description` in
+`app.config.ts` to change its copy. Its home action uses `errors.homeTo` and
+`errors.homeLabel`, matching the recovery screens. Override
+`components/DocsEmptyState.vue` for a different empty-page design; its
+`illustration` slot defaults to the existing `DocsErrorIllustration` component.
+
+### Errors
+
+The layer provides a default `error.vue` for missing pages and fatal errors.
+It preserves the HTTP status code, keeps error pages out of search indexes and
+offers a home link or reload action. The standalone screen avoids loading
+navigation and Content data so it can render when those services fail.
+
+Client-side page failures show a local recovery state inside the layout, keeping
+the header and sidebar available. `DocsExample` isolates each live example;
+retrying remounts its content. Navigating to another route clears the page
+boundary. Server rendering errors still use the standalone error screen.
+
+Content query failures show a retry state with HTTP 500 during server rendering.
+Only a successful query with no matching document is treated as a 404.
+If a request cannot recover in place, retry reloads the current page to start a
+fresh session. Reloads happen only after the user chooses to retry.
+
+Customize the messages and home destination in `app.config.ts`:
+
+```ts
+export default defineAppConfig({
+  selarasDocs: {
+    errors: {
+      homeTo: '/guide/introduction',
+      homeLabel: 'Back to the guide',
+      retryLabel: 'Try again',
+      reloadLabel: 'Reload page',
+      retryingLabel: 'Trying again…',
+      notFound: { title: 'Page not found', description: 'Start again from the guide.' },
+      fatal: { title: 'Something went wrong' },
+      page: { title: 'This page couldn’t load' },
+      example: { title: 'This example couldn’t load' },
+    },
+  },
+})
+```
+
+Home destinations are internal routes resolved under the app's `baseURL`.
+The default destination is `/`. Provide an existing page if your site has no
+homepage. Public recovery copy never includes raw exceptions or stack traces.
+
+Override `components/DocsErrorIllustration.vue` to replace the default geometric
+document illustration. The optional `missing` boolean distinguishes a 404 from
+other errors. Use inherited theme tokens in inline SVGs for light/dark support.
+`DocsErrorState` also exposes an `illustration` slot. Override `DocsErrorPage`
+for the standalone screen's composition, or supply your own `error.vue` for
+application-specific providers. Applications with their own `app.vue` should
+retain the page boundary inside their layout:
+
+```vue
+<template>
+  <NuxtLayout>
+    <DocsErrorBoundary>
+      <NuxtPage />
+    </DocsErrorBoundary>
+  </NuxtLayout>
+</template>
+```
+
 For a host that owns Tailwind compilation or uses a class prefix, set
 `selarasDocs: { css: false }` in `nuxt.config.ts` and import Selaras and the
 docs stylesheet from the host CSS entry.

package/app/app.config.ts

@@ -7,6 +7,7 @@ export default defineAppConfig({
       branch: 'main',
       contentDirectory: 'content',
       editLinks: true,
+      issueLinks: true,
     },
     header: {
       showTitle: true,
@@ -31,7 +32,7 @@ export default defineAppConfig({
       links: [
         {
           label: 'Powered by Selaras',
-          to: 'https://sewadahapp.github.io/selaras',
+          to: 'https://selarasui.my.id',
           target: '_blank',
           rel: 'noreferrer',
         },

package/app/app.vue

@@ -13,7 +13,9 @@ useHead(() => {
 <template>
   <SApp>
     <NuxtLayout>
-      <NuxtPage />
+      <DocsErrorBoundary>
+        <NuxtPage />
+      </DocsErrorBoundary>
     </NuxtLayout>
     <ClientOnly>
       <DocsSearch />

package/app/assets/style.css

@@ -117,6 +117,10 @@
   gap: 3rem;
 }
 
+.selaras-docs-page-grid.selaras-docs-page-grid--wide {
+  grid-template-columns: minmax(0, 1fr);
+}
+
 .selaras-docs-article {
   min-width: 0;
 }
@@ -133,21 +137,53 @@
   width: 14rem;
 }
 
-.selaras-docs-edit-link {
+.selaras-docs-page-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  margin-top: 1.5rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--selaras-resolved-border-default);
+}
+
+.selaras-docs-article > .selaras-docs-page-actions {
+  margin-top: 2.5rem;
+}
+
+.selaras-docs-edit-link,
+.selaras-docs-issue-link {
   display: inline-flex;
+  width: fit-content;
+  min-height: 2rem;
   align-items: center;
-  gap: 0.375rem;
-  margin-top: 2.5rem;
+  gap: 0.5rem;
   color: var(--selaras-resolved-text-muted);
-  font-size: 0.875rem;
+  font-size: 0.8125rem;
+  line-height: 1.5;
   text-decoration: none;
+  text-underline-offset: 0.25em;
+}
+
+.selaras-docs-edit-link .iconify,
+.selaras-docs-issue-link .iconify {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
 }
 
-.selaras-docs-edit-link:hover {
+.selaras-docs-edit-link:hover,
+.selaras-docs-issue-link:hover {
   color: var(--selaras-resolved-text-default);
   text-decoration: underline;
 }
 
+.selaras-docs-edit-link:focus-visible,
+.selaras-docs-issue-link:focus-visible {
+  outline: 2px solid var(--selaras-resolved-color-primary-focus);
+  outline-offset: 3px;
+  border-radius: var(--selaras-resolved-radius-sm);
+}
+
 .selaras-docs-surround {
   margin-top: 2rem;
 }
@@ -219,6 +255,13 @@
   background: var(--selaras-resolved-surface-elevated);
 }
 
+.selaras-docs-footer-attribution-logo {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+  color: var(--selaras-resolved-color-primary-fill);
+}
+
 .selaras-docs-footer-links a:focus-visible {
   outline: 2px solid var(--selaras-resolved-color-primary-fill);
   outline-offset: 2px;
@@ -231,6 +274,10 @@
 }
 
 @media (min-width: 64rem) {
+  .selaras-docs-page-actions--mobile {
+    display: none;
+  }
+
   .selaras-docs-nav-toggle {
     display: none;
   }

package/app/components/DocsEditLink.vue

@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { getDocsRepositoryLinks } from '../utils/repository-links'
+
 const props = defineProps<{
   path: string
 }>()
@@ -6,26 +8,12 @@ const props = defineProps<{
 const appConfig = useAppConfig()
 const docsConfig = computed(() => appConfig.selarasDocs ?? {})
 
-const editUrl = computed(() => {
-  const repository = docsConfig.value.repository
-  if (!repository?.url || repository.editLinks === false)
-    return undefined
-
-  const base = repository.url.replace(/\/$/, '')
-  const relativePath = props.path === '/' ? 'index.md' : `${props.path.replace(/^\//, '')}.md`
-  const contentPath = [repository.contentDirectory ?? 'content', relativePath].join('/')
-  const branch = repository.branch ?? 'main'
-
-  if (base.startsWith('https://github.com/'))
-    return `${base}/edit/${branch}/${contentPath}`
-  if (base.startsWith('https://gitlab.com/'))
-    return `${base}/-/edit/${branch}/${contentPath}`
-  return undefined
-})
+const editUrl = computed(() => getDocsRepositoryLinks(docsConfig.value.repository, props.path).edit)
 </script>
 
 <template>
   <a v-if="editUrl" :href="editUrl" class="selaras-docs-edit-link" target="_blank" rel="noreferrer">
+    <SIcon name="hugeicons:pencil-edit-01" aria-hidden="true" />
     Edit this page
   </a>
 </template>

package/app/components/DocsEmptyState.vue

@@ -0,0 +1,72 @@
+<script setup lang="ts">
+withDefaults(defineProps<{ heading?: 'h1' | 'h2' }>(), { heading: 'h1' })
+
+const appConfig = useAppConfig()
+const config = useRuntimeConfig()
+const headingId = useId()
+const copy = computed(() => appConfig.selarasDocs?.empty ?? {})
+const homeHref = computed(() => {
+  const path = appConfig.selarasDocs?.errors?.homeTo ?? '/'
+  return `${config.app.baseURL.replace(/\/$/, '')}/${path.replace(/^\//, '')}`
+})
+</script>
+
+<template>
+  <section class="selaras-docs-empty-state not-prose" data-docs-empty-state :aria-labelledby="headingId">
+    <div class="selaras-docs-empty-artwork">
+      <slot name="illustration">
+        <DocsErrorIllustration missing />
+      </slot>
+    </div>
+    <component :is="heading" :id="headingId" class="selaras-docs-empty-title">
+      {{ copy.title ?? 'No content yet' }}
+    </component>
+    <p class="selaras-docs-empty-description">
+      {{ copy.description ?? 'There’s no content on this page yet. You can explore the rest of the documentation using the navigation.' }}
+    </p>
+    <SButton as="a" :href="homeHref" variant="outline" color="neutral" class="selaras-docs-empty-action">
+      {{ appConfig.selarasDocs?.errors?.homeLabel ?? 'Back to documentation' }}
+    </SButton>
+  </section>
+</template>
+
+<style scoped>
+.selaras-docs-empty-state {
+  max-width: 32rem;
+  margin: 3rem auto;
+  color: var(--selaras-resolved-text-default);
+  text-align: center;
+}
+
+.selaras-docs-empty-artwork {
+  width: min(100%, 18rem);
+  margin: 0 auto 1.5rem;
+}
+
+.selaras-docs-empty-artwork :deep(svg) {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.selaras-docs-empty-title {
+  margin: 0;
+  font-size: clamp(1.5rem, 1.25rem + 1vw, 2rem);
+  font-weight: 600;
+  line-height: 1.25;
+  letter-spacing: -0.025em;
+  text-wrap: balance;
+}
+
+.selaras-docs-empty-description {
+  max-width: 42ch;
+  margin: 0.875rem auto 0;
+  color: var(--selaras-resolved-text-muted);
+  line-height: 1.7;
+  text-wrap: pretty;
+}
+
+.selaras-docs-empty-action {
+  margin-top: 1.5rem;
+}
+</style>

package/app/components/DocsErrorBoundary.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import type { SelarasDocsErrorKind } from '../../types'
+import { useTemplateRef, watch } from 'vue'
+import { useRouter } from '#app'
+
+const props = withDefaults(defineProps<{
+  kind?: Extract<SelarasDocsErrorKind, 'page' | 'example'>
+  resetKey?: string
+}>(), { kind: 'page' })
+
+const boundary = useTemplateRef('boundary')
+const router = useRouter()
+watch([() => router.currentRoute.value.fullPath, () => props.resetKey], () => boundary.value?.clearError())
+
+function isMissing(error: Error) {
+  return 'statusCode' in error && error.statusCode === 404
+}
+</script>
+
+<template>
+  <NuxtErrorBoundary ref="boundary">
+    <slot />
+    <template #error="{ error, clearError }">
+      <DocsErrorState :kind="kind === 'page' && isMissing(error) ? 'notFound' : kind" @retry="clearError" />
+    </template>
+  </NuxtErrorBoundary>
+</template>

package/app/components/DocsErrorIllustration.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+defineProps<{ missing?: boolean }>()
+</script>
+
+<template>
+  <svg viewBox="0 0 400 240" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
+    <path d="M40 187H360" stroke="var(--selaras-resolved-border-default)" stroke-width="2" stroke-linecap="round" />
+    <rect x="113" y="41" width="148" height="159" rx="12" fill="var(--selaras-resolved-surface-elevated)" stroke="var(--selaras-resolved-border-default)" stroke-width="2" />
+    <path d="M144 24H231L277 70V170C277 177 272 182 265 182H144C137 182 132 177 132 170V36C132 29 137 24 144 24Z" fill="var(--selaras-resolved-surface-default)" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2.5" stroke-linejoin="round" />
+    <path d="M231 25V58C231 65 236 70 243 70H276" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2.5" stroke-linejoin="round" />
+    <path d="M154 61H193M154 84H213" stroke="var(--selaras-resolved-border-default)" stroke-width="5" stroke-linecap="round" />
+    <rect x="154" y="108" width="57" height="48" rx="6" fill="var(--selaras-resolved-color-primary-subtle)" />
+    <path v-if="missing" d="M225 113H254V154H225V113Z" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2" stroke-dasharray="4 5" stroke-linejoin="round" />
+    <path v-else d="M233 116V135M233 146V147" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="4" stroke-linecap="round" />
+    <path d="M56 153C56 122 84 119 105 132M290 109C318 103 342 122 333 146" stroke="var(--selaras-resolved-border-default)" stroke-width="2" stroke-dasharray="4 7" stroke-linecap="round" />
+    <circle cx="55" cy="159" r="6" fill="var(--selaras-resolved-color-primary-fill)" />
+    <rect x="311" y="144" width="44" height="37" rx="6" fill="var(--selaras-resolved-color-primary-subtle)" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2" />
+    <path d="M323 163H343M333 153V173" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2" stroke-linecap="round" />
+  </svg>
+</template>

package/app/components/DocsErrorPage.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+const props = defineProps<{ error: NuxtError }>()
+const config = useRuntimeConfig()
+const appConfig = useAppConfig()
+const siteName = computed(() => appConfig.selarasDocs?.site?.name ?? 'Documentation')
+const missing = computed(() => props.error.statusCode === 404)
+const pending = ref(false)
+
+useSeoMeta({
+  title: () => `${missing.value ? 'Page not found' : 'Something went wrong'} — ${siteName.value}`,
+  robots: 'noindex',
+})
+
+function reload() {
+  pending.value = true
+  window.location.reload()
+}
+
+async function goHome(event: MouseEvent) {
+  event.preventDefault()
+  const path = appConfig.selarasDocs?.errors?.homeTo ?? '/'
+  try {
+    await clearError({ redirect: path })
+  }
+  catch {
+    window.location.assign(`${config.app.baseURL.replace(/\/$/, '')}/${path.replace(/^\//, '')}`)
+  }
+}
+</script>
+
+<template>
+  <div class="selaras-docs-root selaras-docs-error-page">
+    <header class="selaras-docs-error-header">
+      <a :href="config.app.baseURL" class="selaras-docs-error-brand" :aria-label="`${siteName} home`">
+        <DocsLogo />
+        <span>{{ siteName }}</span>
+      </a>
+    </header>
+    <main class="selaras-docs-error-main">
+      <DocsErrorState :kind="missing ? 'notFound' : 'fatal'" :pending="pending" @retry="reload" @home="goHome" />
+    </main>
+  </div>
+</template>
+
+<style scoped>
+.selaras-docs-error-page {
+  min-height: 100svh;
+  color: var(--selaras-resolved-text-default);
+}
+
+.selaras-docs-error-header {
+  width: min(100%, 90rem);
+  margin: 0 auto;
+  padding: 1.5rem;
+}
+
+.selaras-docs-error-brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.75rem;
+  color: inherit;
+  font-size: 1.125rem;
+  font-weight: 650;
+  text-decoration: none;
+}
+
+.selaras-docs-error-brand:focus-visible {
+  border-radius: var(--selaras-resolved-radius-sm);
+  outline: 2px solid var(--selaras-resolved-color-primary-focus);
+  outline-offset: 4px;
+}
+
+.selaras-docs-error-main {
+  display: grid;
+  align-items: center;
+  min-height: calc(100svh - 6rem);
+  padding: 1.5rem 1.5rem 5rem;
+}
+</style>

package/app/components/DocsErrorState.vue

@@ -0,0 +1,161 @@
+<script setup lang="ts">
+import type { SelarasDocsErrorKind } from '../../types'
+
+const props = withDefaults(defineProps<{
+  kind?: SelarasDocsErrorKind
+  pending?: boolean
+  showHome?: boolean
+}>(), { kind: 'page', pending: false, showHome: undefined })
+
+const emit = defineEmits<{ retry: [], home: [event: MouseEvent] }>()
+const appConfig = useAppConfig()
+const config = useRuntimeConfig()
+const homeHref = computed(() => {
+  const path = appConfig.selarasDocs?.errors?.homeTo ?? '/'
+  const base = config.app.baseURL.replace(/\/$/, '')
+  return `${base}/${path.replace(/^\//, '')}`
+})
+const headingId = useId()
+const heading = useTemplateRef<HTMLElement>('heading')
+onMounted(() => {
+  if (props.kind !== 'example')
+    heading.value?.focus({ preventScroll: true })
+})
+const copy = computed(() => {
+  const defaults = {
+    notFound: { title: 'Page not found', description: 'The link may have changed, or this page may no longer exist. You can start again from the homepage.' },
+    fatal: { title: 'Something went wrong', description: 'We couldn’t load this page. Reload it to try again, or return to the homepage.' },
+    page: { title: 'This page couldn’t load', description: 'Please try again. You can still use the navigation to explore other pages.' },
+    example: { title: 'This example couldn’t load', description: 'Try loading the example again. The rest of the documentation is still available.' },
+  }
+  return { ...defaults[props.kind], ...appConfig.selarasDocs?.errors?.[props.kind] }
+})
+const labels = computed(() => appConfig.selarasDocs?.errors ?? {})
+const showHome = computed(() => props.showHome ?? props.kind !== 'example')
+</script>
+
+<template>
+  <section
+    class="selaras-docs-error-state not-prose"
+    :data-error-kind="kind"
+    :aria-labelledby="headingId"
+    :role="kind === 'example' ? 'alert' : undefined"
+  >
+    <div class="selaras-docs-error-artwork">
+      <slot name="illustration">
+        <DocsErrorIllustration :missing="kind === 'notFound'" />
+      </slot>
+    </div>
+    <div class="selaras-docs-error-copy">
+      <component :is="kind === 'example' ? 'h3' : 'h1'" :id="headingId" ref="heading" class="selaras-docs-error-title" :tabindex="kind === 'example' ? undefined : -1">
+        {{ copy.title }}
+      </component>
+      <p class="selaras-docs-error-description">
+        {{ copy.description }}
+      </p>
+      <div class="selaras-docs-error-actions">
+        <SButton v-if="kind !== 'notFound'" :loading="pending" :disabled="pending" @click="emit('retry')">
+          {{ pending ? labels.retryingLabel ?? 'Trying again…' : kind === 'fatal' ? labels.reloadLabel ?? 'Reload page' : labels.retryLabel ?? 'Try again' }}
+        </SButton>
+        <SButton v-if="showHome" as="a" :href="homeHref" :variant="kind === 'notFound' ? 'solid' : 'outline'" :color="kind === 'notFound' ? 'primary' : 'neutral'" @click="emit('home', $event)">
+          {{ labels.homeLabel ?? 'Go to homepage' }}
+        </SButton>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.selaras-docs-error-state {
+  width: min(100%, 42rem);
+  margin: 3rem auto;
+  color: var(--selaras-resolved-text-default);
+  text-align: center;
+}
+
+.selaras-docs-error-artwork {
+  width: min(100%, 22rem);
+  margin: 0 auto 1.5rem;
+}
+
+.selaras-docs-error-artwork :deep(svg) {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.selaras-docs-error-title {
+  margin: 0;
+  font-size: clamp(1.75rem, 1.4rem + 1vw, 2.5rem);
+  font-weight: 650;
+  line-height: 1.15;
+  letter-spacing: -0.025em;
+  text-wrap: balance;
+}
+
+.selaras-docs-error-title:focus {
+  outline: none;
+}
+
+.selaras-docs-error-description {
+  max-width: 44ch;
+  margin: 1rem auto 0;
+  color: var(--selaras-resolved-text-muted);
+  font-size: 1rem;
+  line-height: 1.7;
+}
+
+.selaras-docs-error-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.75rem;
+  margin-top: 1.75rem;
+}
+
+.selaras-docs-error-state[data-error-kind="example"] {
+  display: flex;
+  align-items: center;
+  gap: 1.25rem;
+  width: 100%;
+  margin: 0;
+  padding: 1.5rem;
+  border: 1px solid var(--selaras-resolved-border-default);
+  border-radius: var(--selaras-resolved-radius-lg);
+  background: var(--selaras-resolved-surface-elevated);
+  text-align: start;
+}
+
+[data-error-kind="example"] .selaras-docs-error-artwork {
+  flex: none;
+  width: 6rem;
+  margin: 0;
+}
+
+[data-error-kind="example"] .selaras-docs-error-title {
+  font-size: 1rem;
+  line-height: 1.4;
+  letter-spacing: normal;
+}
+
+[data-error-kind="example"] .selaras-docs-error-description {
+  margin: 0.375rem 0 0;
+  font-size: 0.875rem;
+}
+
+[data-error-kind="example"] .selaras-docs-error-actions {
+  justify-content: flex-start;
+  margin-top: 1rem;
+}
+
+@media (max-width: 30rem) {
+  .selaras-docs-error-state[data-error-kind="example"] {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  [data-error-kind="example"] .selaras-docs-error-artwork {
+    display: none;
+  }
+}
+</style>

package/app/components/DocsFooter.vue

@@ -18,6 +18,11 @@ const footer = computed(() => docsConfig.value.footer)
           :aria-label="link.ariaLabel ?? link.label"
         >
           <SIcon v-if="link.icon" :name="link.icon" />
+          <svg v-else-if="link.to === 'https://selarasui.my.id'" class="selaras-docs-footer-attribution-logo" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true" focusable="false">
+            <path d="M28 80 H68 C94 80 118 36 144 36 H228 V62 H144 C118 62 94 106 68 106 H28 Z" />
+            <path d="M28 134 H68 C94 134 118 90 144 90 H228 V116 H144 C118 116 94 160 68 160 H28 Z" />
+            <path d="M28 188 H68 C94 188 118 144 144 144 H228 V170 H144 C118 170 94 214 68 214 H28 Z" />
+          </svg>
           <span v-if="link.label">{{ link.label }}</span>
         </NuxtLink>
       </nav>

package/app/components/DocsPageActions.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import { getDocsRepositoryLinks } from '../utils/repository-links'
+
+const props = withDefaults(defineProps<{
+  path: string
+  title?: string
+  editLink?: boolean
+  issueLink?: boolean
+}>(), { editLink: true, issueLink: true })
+
+const appConfig = useAppConfig()
+const links = computed(() => getDocsRepositoryLinks(appConfig.selarasDocs?.repository, props.path, props.title))
+const hasEditLink = computed(() => props.editLink && !!links.value.edit)
+const hasIssueLink = computed(() => props.issueLink && !!links.value.issue)
+</script>
+
+<template>
+  <nav v-if="hasEditLink || hasIssueLink" class="selaras-docs-page-actions" aria-label="Page actions">
+    <DocsEditLink v-if="hasEditLink" :path="path" />
+    <a v-if="hasIssueLink" :href="links.issue" target="_blank" rel="noreferrer" class="selaras-docs-issue-link">
+      <SIcon name="hugeicons:bug-01" aria-hidden="true" />
+      Report an issue
+    </a>
+  </nav>
+</template>

package/app/components/DocsTableOfContents.vue

@@ -17,5 +17,6 @@ const docsConfig = computed(() => appConfig.selarasDocs ?? {})
     :ui="{ root: 'top-16 h-[calc(100vh-4rem)]' }"
   >
     <SContentToc :links="links" :title="docsConfig.toc?.title" />
+    <slot />
   </SPageAside>
 </template>

package/app/components/DocsThemePicker.vue

@@ -0,0 +1,3 @@
+<template>
+  <slot />
+</template>

package/app/components/content/DocsExample.vue

@@ -18,7 +18,9 @@ const resolvedComponent = computed(() => {
 
 <template>
   <section v-if="resolvedComponent" :data-example="name">
-    <component :is="resolvedComponent" />
+    <DocsErrorBoundary kind="example" :reset-key="name">
+      <component :is="resolvedComponent" />
+    </DocsErrorBoundary>
   </section>
   <p v-else role="alert">
     Example "{{ name }}" not found

package/app/error.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+defineProps<{ error: NuxtError }>()
+</script>
+
+<template>
+  <SApp>
+    <DocsErrorPage :error="error" />
+  </SApp>
+</template>

package/app/pages/[...slug].vue

@@ -10,14 +10,30 @@ import ProsePre from '@sewadah/selaras/components/ProsePre.vue'
 
 const route = useRoute()
 const appConfig = useAppConfig()
-const { data: page } = await useAsyncData(`selaras-docs:${route.path}`, () => queryCollection('docs').path(route.path).first())
+const { data: page, error, status, refresh } = await useAsyncData(`selaras-docs:${route.path}`, () => queryCollection('docs').path(route.path).first())
 
-if (!page.value) {
+if (!page.value && !error.value) {
   throw createError({ statusCode: 404, statusMessage: 'Documentation page not found', fatal: true })
 }
+if (import.meta.server && error.value)
+  setResponseStatus(500)
+
+async function retryPage() {
+  await refresh()
+  if (import.meta.client && error.value) {
+    window.location.reload()
+    return
+  }
+  if (!page.value && !error.value)
+    showError({ statusCode: 404, statusMessage: 'Documentation page not found' })
+}
 
 definePageMeta({ layout: 'selaras-docs' })
-useSeoMeta({ title: page.value.title, description: page.value.description ?? appConfig.selarasDocs?.site?.description })
+useSeoMeta({
+  title: () => page.value?.title ?? appConfig.selarasDocs?.errors?.page?.title ?? 'Documentation unavailable',
+  description: () => page.value?.description ?? appConfig.selarasDocs?.site?.description,
+  robots: () => error.value ? 'noindex' : undefined,
+})
 useHead(() => ({
   ...(appConfig.selarasDocs?.site?.titleTemplate && { titleTemplate: appConfig.selarasDocs.site.titleTemplate }),
   ...(appConfig.selarasDocs?.site?.url && {
@@ -36,18 +52,30 @@ const proseComponents = {
 }
 
 const tocLinks = computed(() => (page.value?.body?.toc?.links ?? []) as unknown as TocLink[])
+const hasToc = computed(() => page.value?.toc !== false && page.value?.aside !== false && appConfig.selarasDocs?.toc?.enabled !== false && tocLinks.value.length > 0)
 const surround = useDocsSurround()
 </script>
 
 <template>
-  <SContainer size="full" class="selaras-docs-page" :class="{ 'selaras-docs-page--fluid': appConfig.selarasDocs?.main?.fluid }">
-    <div class="selaras-docs-page-grid">
+  <DocsErrorState v-if="error || !page" kind="page" :pending="status === 'pending'" @retry="retryPage" />
+  <SContainer v-else size="full" class="selaras-docs-page" :class="{ 'selaras-docs-page--fluid': appConfig.selarasDocs?.main?.fluid }">
+    <div class="selaras-docs-page-grid" :class="{ 'selaras-docs-page-grid--wide': !hasToc }">
       <article class="selaras-docs-article">
         <p v-if="page!.description" class="selaras-docs-description">
           {{ page!.description }}
         </p>
-        <ContentRenderer :value="page!" :components="proseComponents" class="selaras-docs-content selaras-prose" />
-        <DocsEditLink v-if="page!.editLink !== false" :path="route.path" />
+        <ContentRenderer :value="page!" :components="proseComponents" class="selaras-docs-content selaras-prose">
+          <template #empty>
+            <DocsEmptyState />
+          </template>
+        </ContentRenderer>
+        <DocsPageActions
+          :path="route.path"
+          :title="page!.title"
+          :edit-link="page!.editLink !== false"
+          :issue-link="page!.issueLink !== false"
+          :class="{ 'selaras-docs-page-actions--mobile': hasToc }"
+        />
         <SContentSurround
           v-if="page!.prevNext !== false"
           :prev="surround.prev"
@@ -55,7 +83,9 @@ const surround = useDocsSurround()
           class="selaras-docs-surround"
         />
       </article>
-      <DocsTableOfContents v-if="page!.toc !== false && page!.aside !== false" :links="tocLinks" />
+      <DocsTableOfContents v-if="hasToc" :links="tocLinks">
+        <DocsPageActions :path="route.path" :title="page!.title" :edit-link="page!.editLink !== false" :issue-link="page!.issueLink !== false" />
+      </DocsTableOfContents>
     </div>
   </SContainer>
 </template>

package/app/utils/repository-links.ts

@@ -0,0 +1,29 @@
+import type { SelarasDocsAppConfig } from '../../types'
+
+export function getDocsRepositoryLinks(repository: SelarasDocsAppConfig['repository'], path: string, title?: string) {
+  const links: { edit?: string, issue?: string } = {}
+  const base = repository?.url?.replace(/\/$/, '')
+  const github = base?.startsWith('https://github.com/')
+  const gitlab = base?.startsWith('https://gitlab.com/')
+
+  if (base && (github || gitlab) && repository?.editLinks !== false) {
+    const relativePath = path === '/' ? 'index.md' : `${path.replace(/^\//, '')}.md`
+    const contentPath = [repository?.contentDirectory ?? 'content', relativePath].join('/')
+    const branch = repository?.branch ?? 'main'
+    links.edit = `${base}/${gitlab ? '-/edit' : 'edit'}/${branch}/${contentPath}`
+  }
+
+  if (repository?.issueLinks !== false) {
+    if (repository?.issueUrl) {
+      links.issue = repository.issueUrl
+    }
+    else if (base && (github || gitlab)) {
+      const url = new URL(`${base}/${gitlab ? '-/issues/new' : 'issues/new'}`)
+      url.searchParams.set(gitlab ? 'issue[title]' : 'title', `Documentation: ${title ?? path}`)
+      url.searchParams.set(gitlab ? 'issue[description]' : 'body', `Documentation page: ${path}\n\n`)
+      links.issue = url.href
+    }
+  }
+
+  return links
+}

package/content.config.ts

@@ -42,6 +42,7 @@ export default defineContentConfig({
         toc: z.boolean().default(true),
         aside: z.boolean().default(true),
         editLink: z.boolean().default(true),
+        issueLink: z.boolean().default(true),
         prevNext: z.boolean().default(true),
       }),
     }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sewadah/selaras-docs",
   "type": "module",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Nuxt Content documentation layer for Selaras",
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
   "dependencies": {
     "@nuxt/content": "^3.16.0",
     "@nuxt/kit": "^4.5.2",
-    "@sewadah/selaras": "^0.8.0",
+    "@sewadah/selaras": "^0.9.0",
     "tailwindcss": "^4.3.0"
   }
 }

package/types.d.ts

@@ -37,7 +37,28 @@ export interface SelarasDocsLogo {
   tint?: boolean
 }
 
+export type SelarasDocsErrorKind = 'notFound' | 'fatal' | 'page' | 'example'
+
+export interface SelarasDocsErrorCopy {
+  title?: string
+  description?: string
+}
+
 export interface SelarasDocsAppConfig {
+  /** Copy shown for an existing Markdown page with no body content. */
+  empty?: {
+    title?: string
+    description?: string
+  }
+  /** Recovery messages and the destination of error-screen home links. */
+  errors?: Partial<Record<SelarasDocsErrorKind, SelarasDocsErrorCopy>> & {
+    /** An internal route, resolved under the application's base URL. @default '/' */
+    homeTo?: string
+    homeLabel?: string
+    retryLabel?: string
+    reloadLabel?: string
+    retryingLabel?: string
+  }
   site?: {
     name?: string
     description?: string
@@ -54,13 +75,17 @@ export interface SelarasDocsAppConfig {
     branch?: string
     contentDirectory?: string
     editLinks?: boolean
+    /** Show a page-context issue link. @default true */
+    issueLinks?: boolean
+    /** Override the new-issue destination, e.g. for a separate issue tracker. */
+    issueUrl?: string
   }
   header?: {
     title?: string
     showTitle?: boolean
     search?: boolean
     colorMode?: boolean
-    /** Show the consuming site's visual preset picker. @default false */
+    /** Show the consuming site's DocsThemePicker component; the layer default is empty. @default false */
     themePicker?: boolean
     /** Let the header span the viewport instead of the docs shell width. */
     fluid?: boolean