@sewadah/selaras-docs 1.2.4 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## v1.3.1
+
+[compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.3.0...selaras-docs-v1.3.1)
+
+### 🚀 Enhancements
+
+- **feat(docs):** prepare Cloudflare Markdown negotiation rules ([7beb431](https://github.com/sewadahapp/selaras/commit/7beb431ac798eb24fc4021d01b93cd477cca34ee))
+- **feat(docs):** declare AI content usage preferences ([2434ffe](https://github.com/sewadahapp/selaras/commit/2434ffe475b63c862ca1575afb90a497b4742699))
+- **feat(docs):** declare explicit AI crawler access rules ([a2a624c](https://github.com/sewadahapp/selaras/commit/a2a624cbfdaa56cc9fa77d63bdcf08578e22e421))
+- **feat(docs):** generate robots.txt with sitemap discovery ([a8e4ed6](https://github.com/sewadahapp/selaras/commit/a8e4ed6fc7c97beccb3dfab7796ce085d9befa8f))
+- **feat(toolbar):** add shared controls and editor blocks ([dc56fd8](https://github.com/sewadahapp/selaras/commit/dc56fd8d92e19cefe37bd7b261c08937bafaa02c))
+- **feat(docs):** redesign homepage with interactive previews ([878a542](https://github.com/sewadahapp/selaras/commit/878a542f10b0c8310eed4be8759bd80f5017e800))
+- **feat(editable):** add inline text editing with draft controls ([078649e](https://github.com/sewadahapp/selaras/commit/078649e219dfcf4553a02e3f3a6ae0a8914d7bf0))
+
+### 🩹 Fixes
+
+- **fix(docs):** make editor read-only labels clickable ([8c521f2](https://github.com/sewadahapp/selaras/commit/8c521f2c84610f1df9b4e5953bed990d0b0ec9aa))
+- **fix(forms):** unify clear button styling and behavior ([c669eb3](https://github.com/sewadahapp/selaras/commit/c669eb39f7c6f7246a892804447e95a533c327c8))
+- **fix(forms):** align field and button heights across sizes ([818c325](https://github.com/sewadahapp/selaras/commit/818c325b24525927be85a21a7c46a875484fc6f0))
+- **fix(listbox):** reuse checkbox component for selection indicators ([1abf48b](https://github.com/sewadahapp/selaras/commit/1abf48b75004754de1ea38a796015ae978047c76))
+
+### 📖 Documentation
+
+- **docs(agent):** request optional source attribution ([e279f40](https://github.com/sewadahapp/selaras/commit/e279f4050edae50be0b1e85f085eaa8ea82a9781))
+
+### 🤖 Other changes
+
+- **ci:** enforce conventional commits and pre-commit checks ([1b5922f](https://github.com/sewadahapp/selaras/commit/1b5922f5b8534920f9c054d1611ebc2eb7dc377d))
+
+Published against `@sewadah/selaras` ^0.10.0.
+
+## 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)

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,13 +138,34 @@ 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

package/app/app.config.ts

@@ -7,6 +7,7 @@ export default defineAppConfig({
       branch: 'main',
       contentDirectory: 'content',
       editLinks: true,
+      issueLinks: true,
     },
     header: {
       showTitle: true,

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/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/pages/[...slug].vue

@@ -52,19 +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>
   <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">
+    <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"
@@ -72,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.4",
+  "version": "1.3.1",
   "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.9.0",
+    "@sewadah/selaras": "^0.10.0",
     "tailwindcss": "^4.3.0"
   }
 }

package/types.d.ts

@@ -45,6 +45,11 @@ export interface SelarasDocsErrorCopy {
 }
 
 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 '/' */
@@ -70,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