@hgdc/docs 0.4.3 → 0.5.0

package/docs.schema.json

@@ -233,6 +233,21 @@
         }
       }
     },
+    "app": {
+      "type": "object",
+      "properties": {
+        "href": {
+          "type": "string",
+          "format": "uri"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 40
+        }
+      },
+      "required": ["href"]
+    },
     "footer": {
       "type": "object",
       "properties": {
@@ -245,6 +260,50 @@
             "type": "string",
             "format": "uri"
           }
+        },
+        "links": {
+          "maxItems": 6,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "header": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 40
+              },
+              "items": {
+                "minItems": 1,
+                "maxItems": 12,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "label": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 60
+                    },
+                    "href": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "icon": {
+                      "type": "string",
+                      "pattern": "^\\/(?!\\/)[\\w./-]+$"
+                    }
+                  },
+                  "required": ["label", "href"]
+                }
+              }
+            },
+            "required": ["items"]
+          }
+        },
+        "copyright": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hgdc/docs",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Modèle de site de HGDC Docs : documentation MDX (docs.json) construite avec Astro Starlight, recherche, versions, llms.txt et assistant.",
   "license": "UNLICENSED",
   "type": "module",

package/src/core/config.ts

@@ -82,6 +82,25 @@ export function socialNetwork(key: string): (typeof SOCIAL_NETWORKS)[keyof typeo
   return SOCIAL_NETWORKS[name] ?? null
 }
 
+/**
+ * Lien du pied de page : un chemin du site (« /guides/publier », préfixé par `base`), une
+ * adresse https:// ou mailto:. `icon` : image du site (« /images/x.svg ») affichée devant.
+ */
+const footerLink = z.object({
+  label: z.string().min(1).max(60),
+  href: z
+    .string()
+    .min(1)
+    .refine(
+      (value) => /^\/(?!\/)/.test(value) || /^https:\/\/[^\s]+$/.test(value) || /^mailto:[^\s@]+@[^\s@]+$/.test(value),
+      "lien attendu : un chemin du site (« /… »), une adresse https:// ou mailto:",
+    ),
+  icon: z
+    .string()
+    .regex(/^\/(?!\/)[\w./-]+$/, "image attendue : un chemin du site (ex. /images/logo.svg)")
+    .optional(),
+})
+
 const REDIRECT_SOURCE = /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/
 
 /** Ancienne adresse vers la nouvelle (champ `redirects` de Mintlify), sans motif. */
@@ -126,7 +145,34 @@ export const docsConfigSchema = z.object({
       primary: z.object({ label: z.string(), href: z.url() }).optional(),
     })
     .optional(),
-  footer: z.object({ socials: z.record(z.string(), z.url()).optional() }).optional(),
+  /**
+   * Application que la doc accompagne (champ HGDC) : bouton « Ouvrir <name> » dans l'en-tête
+   * et en tête du menu de téléphone. Sans lui, la lectrice n'a aucun chemin vers le produit.
+   */
+  app: z
+    .object({
+      href: z.url({ protocol: /^https$/, error: "adresse attendue, en https://" }),
+      /** Libellé du bouton ; « Ouvrir <name> » par défaut. */
+      label: z.string().min(1).max(40).optional(),
+    })
+    .optional(),
+  footer: z
+    .object({
+      socials: z.record(z.string(), z.url()).optional(),
+      /** Colonnes de liens (champ `footer.links` de Mintlify), plus une `icon` facultative par lien. */
+      links: z
+        .array(
+          z.object({
+            header: z.string().min(1).max(40).optional(),
+            items: z.array(footerLink).min(1, "une colonne contient au moins un lien").max(12),
+          }),
+        )
+        .max(6, "6 colonnes au plus")
+        .optional(),
+      /** Titulaire affiché après « © <année> » au bas du pied (champ HGDC) ; `name` par défaut. */
+      copyright: z.string().min(1).max(80).optional(),
+    })
+    .optional(),
   redirects: z.array(redirect).max(500, "500 redirections au plus").optional(),
   assistant: z
     .object({

package/src/overrides/Header.astro

@@ -2,14 +2,17 @@
 import Search from "virtual:starlight/components/Search"
 import data from "virtual:hgdc-docs/config"
 
-import { assistantEnabled, docsSections, sectionHref } from "./sections.ts"
+import { appLink, assistantEnabled, docsSections, sectionHref } from "./sections.ts"
 import Icon from "./Icon.astro"
 import ThemeToggle from "./ThemeToggle.astro"
 
 /**
  * En-tête, comme chez Mintlify : produit à gauche, onglets de docs.json au centre, puis la
  * recherche, l'assistant, les liens de `navbar` et le thème. Sur téléphone, le menu, le
- * produit, la recherche et l'assistant seulement : le reste passe dans le menu.
+ * produit, la recherche, l'assistant et « Ouvrir <produit> » : le reste passe dans le menu.
+ *
+ * Le nom du produit mène à l'accueil de la doc (on reste dans le site qu'on lit, comme le
+ * logo de tout site) ; le chemin vers l'application est le bouton « Ouvrir <produit> » (`app`).
  */
 const { tabs, current } = docsSections(data.tree, Astro.locals.hgdcSection ?? 0)
 const home = `${data.base}/`
@@ -18,6 +21,7 @@ const src = (path: string) => `${data.base}${path.startsWith("/") ? path : `/${p
 const links = data.config.navbar?.links ?? []
 const primary = data.config.navbar?.primary
 const assistant = assistantEnabled(data.config)
+const app = appLink(data.config)
 ---
 
 <div class="hd-header">
@@ -88,5 +92,13 @@ const assistant = assistantEnabled(data.config)
       )
     }
     <ThemeToggle variant="button" />
+    {
+      app && (
+        <a class="hd-pill hd-pill--primary hd-app-button" href={app.href}>
+          {app.label}
+          <Icon name="arrow-up-right" size={16} />
+        </a>
+      )
+    }
   </div>
 </div>

package/src/overrides/Sidebar.astro

@@ -2,14 +2,14 @@
 import data from "virtual:hgdc-docs/config"
 
 import Icon from "./Icon.astro"
-import { docsSections, sectionHref } from "./sections.ts"
+import { appLink, docsSections, sectionHref } from "./sections.ts"
 import SidebarList from "./SidebarList.astro"
 import ThemeToggle from "./ThemeToggle.astro"
 
 /**
  * Barre latérale : la version (s'il y en a plusieurs), puis les groupes de docs.json. Sur
  * téléphone, le même panneau sert de menu : il reprend les onglets et les liens de
- * l'en-tête, et le choix du thème.
+ * l'en-tête, le bouton vers l'application et le choix du thème.
  */
 const { tabs, versions, current } = docsSections(data.tree, Astro.locals.hgdcSection ?? 0)
 const tabPosition = current.version.tabs.indexOf(current.tab)
@@ -17,6 +17,7 @@ const versionHref = (version: (typeof versions)[number]) =>
   sectionHref(data.base, (version.tabs[tabPosition] ?? version.tabs[0]!).items)
 const links = data.config.navbar?.links ?? []
 const primary = data.config.navbar?.primary
+const app = appLink(data.config)
 ---
 
 <div class="hd-mobile-only hd-sidebar-head">
@@ -25,6 +26,14 @@ const primary = data.config.navbar?.primary
     <Icon name="x" />
   </button>
 </div>
+{
+  app && (
+    <a class="hd-mobile-only hd-pill hd-pill--primary hd-sidebar-app" href={app.href}>
+      {app.label}
+      <Icon name="arrow-up-right" size={16} />
+    </a>
+  )
+}
 
 {
   versions.length > 1 && (

package/src/overrides/SiteFooter.astro

@@ -3,49 +3,93 @@ import { Icon as StarlightIcon } from "@astrojs/starlight/components"
 import data from "virtual:hgdc-docs/config"
 
 import { socialNetwork } from "../core/config.ts"
+import { withBase } from "../core/navigation.ts"
+import Icon from "./Icon.astro"
+import { appLink } from "./sections.ts"
 import ThemeToggle from "./ThemeToggle.astro"
 
 /**
- * Pied de page du site, à droite de la barre latérale : le produit, ses réseaux
- * (`footer.socials`) et le choix du thème.
+ * Pied de page du site, à droite de la barre latérale. En haut, le produit (logo, phrase,
+ * bouton vers l'application, réseaux) et les colonnes de `footer.links` ; en bas, « © année
+ * titulaire » et le choix du thème. Tout vient de docs.json : le modèle n'invente aucun lien.
  */
 const logo = typeof data.config.logo === "string" ? { light: data.config.logo } : data.config.logo
-const src = (path: string) => `${data.base}${path.startsWith("/") ? path : `/${path}`}`
+const src = (path: string) => withBase(data.base, path.startsWith("/") ? path : `/${path}`)
 const socials = Object.entries(data.config.footer?.socials ?? {}).flatMap(([key, href]) => {
   const network = socialNetwork(key)
   return network ? [{ ...network, href }] : []
 })
+const columns = data.config.footer?.links ?? []
+const app = appLink(data.config)
+const owner = data.config.footer?.copyright ?? data.config.name
+const year = new Date().getFullYear()
 ---
 
 <footer class="hd-site-footer" data-pagefind-ignore>
-  <div class="hd-site-footer__row">
-    <a class="hd-brand hd-brand--footer" href={`${data.base}/`}>
+  <div class="hd-site-footer__top">
+    <div class="hd-site-footer__about">
+      <a class="hd-brand hd-brand--footer" href={`${data.base}/`}>
+        {
+          logo && (
+            <span class="hd-brand__mark">
+              <img class="hd-brand__light" src={src(logo.light)} alt="" width="20" height="20" loading="lazy" />
+              <img class="hd-brand__dark" src={src(logo.dark ?? logo.light)} alt="" width="20" height="20" loading="lazy" />
+            </span>
+          )
+        }
+        <span class="hd-brand__name">{data.config.name}</span>
+      </a>
+      {data.config.description && <p class="hd-site-footer__lede">{data.config.description}</p>}
       {
-        logo && (
-          <span class="hd-brand__mark">
-            <img class="hd-brand__light" src={src(logo.light)} alt="" width="20" height="20" loading="lazy" />
-            <img class="hd-brand__dark" src={src(logo.dark ?? logo.light)} alt="" width="20" height="20" loading="lazy" />
-          </span>
+        app && (
+          <a class="hd-pill hd-pill--ghost hd-site-footer__app" href={app.href}>
+            {app.label}
+            <Icon name="arrow-up-right" size={16} />
+          </a>
         )
       }
-      <span class="hd-brand__name">{data.config.name}</span>
-    </a>
+      {
+        socials.length > 0 && (
+          <ul class="hd-socials" aria-label="Réseaux">
+            {socials.map((social) => (
+              <li>
+                <a class="hd-icon-button" href={social.href} rel="me noopener" aria-label={social.label} title={social.label}>
+                  <StarlightIcon name={social.icon as "github"} size="1.1rem" />
+                </a>
+              </li>
+            ))}
+          </ul>
+        )
+      }
+    </div>
     {
-      socials.length > 0 && (
-        <ul class="hd-socials" aria-label="Réseaux">
-          {socials.map((social) => (
-            <li>
-              <a class="hd-icon-button" href={social.href} rel="me noopener" aria-label={social.label} title={social.label}>
-                <StarlightIcon name={social.icon as "github"} size="1.1rem" />
-              </a>
-            </li>
+      columns.length > 0 && (
+        <nav class="hd-site-footer__columns" aria-label="Pied de page">
+          {columns.map((column, index) => (
+            <div class="hd-site-footer__column">
+              {column.header && (
+                <h2 class="hd-site-footer__heading" id={`hd-footer-col-${index}`}>
+                  {column.header}
+                </h2>
+              )}
+              <ul aria-labelledby={column.header ? `hd-footer-col-${index}` : undefined}>
+                {column.items.map((item) => (
+                  <li>
+                    <a class="hd-site-footer__link" href={withBase(data.base, item.href)}>
+                      {item.icon && <img src={src(item.icon)} alt="" width="18" height="18" loading="lazy" />}
+                      <span>{item.label}</span>
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </div>
           ))}
-        </ul>
+        </nav>
       )
     }
   </div>
-  <div class="hd-site-footer__row hd-site-footer__row--meta">
-    {data.config.description && <p>{data.config.description}</p>}
+  <div class="hd-site-footer__bottom">
+    <p class="hd-site-footer__legal">© {year} {owner}</p>
     <ThemeToggle variant="segmented" />
   </div>
 </footer>

package/src/overrides/sections.ts

@@ -27,3 +27,8 @@ export function sectionHref(base: string, items: Array<NavItem>): string {
 export function assistantEnabled(config: DocsConfig): boolean {
   return Boolean(config.project) && config.assistant?.enabled !== false
 }
+
+/** Bouton vers l'application (`app`) : « Ouvrir <name> » sauf libellé donné. */
+export function appLink(config: DocsConfig): { href: string; label: string } | null {
+  return config.app ? { href: config.app.href, label: config.app.label ?? `Ouvrir ${config.name}` } : null
+}

package/src/styles/theme.css

@@ -326,6 +326,30 @@ body {
 .hd-header__links {
   display: none;
 }
+/* « Ouvrir <produit> » : toujours visible, le seul chemin vers l'application. Sur un
+   téléphone étroit, le logo seul tient lieu de nom pour lui laisser la place. */
+.hd-app-button {
+  height: 2.25rem;
+  padding: 0 0.75rem 0 0.875rem;
+  gap: 0.25rem;
+  margin-inline-start: 0.25rem;
+  font-size: 0.8125rem;
+}
+@media (max-width: 29.99em) {
+  .hd-header:has(.hd-app-button) .hd-brand:has(.hd-brand__mark) .hd-brand__name {
+    display: none;
+  }
+}
+@media (min-width: 50em) {
+  .hd-app-button {
+    padding: 0 0.875rem 0 1rem;
+    font-size: 0.875rem;
+  }
+}
+.hd-sidebar-app {
+  align-self: stretch;
+  height: 2.75rem;
+}
 
 .hd-brand {
   display: inline-flex;
@@ -788,25 +812,28 @@ starlight-toc ul ul {
 }
 starlight-toc a {
   display: block;
-  padding: 0.3rem 0 0.3rem 0.875rem;
-  border-inline-start: 1px solid var(--hd-border);
+  padding: 0.3rem 0;
   color: var(--hd-muted-fg);
   font: 400 0.8125rem/1.4 var(--hd-font-sans);
   text-decoration: none;
   transition: color 120ms ease;
 }
 starlight-toc ul ul a {
-  margin-inline-start: -0.75rem;
-  padding-inline-start: 1.625rem;
+  margin-inline-start: 0;
+  padding-inline-start: 0;
 }
 starlight-toc a:hover {
   color: var(--hd-fg);
 }
 starlight-toc a[aria-current="true"] {
-  border-inline-start-color: var(--hd-accent);
   color: var(--hd-accent);
   font-weight: 500;
 }
+starlight-toc a:focus-visible {
+  border-radius: 0.25rem;
+  outline: 2px solid var(--hd-accent);
+  outline-offset: 2px;
+}
 starlight-toc a .hd-method {
   display: none;
 }
@@ -1811,25 +1838,75 @@ starlight-tabs [role="tabpanel"] {
 /* --- Pied de page du site --- */
 
 .hd-site-footer {
-  display: grid;
-  gap: 1.25rem;
-  margin: 2rem var(--hd-gutter) 0;
-  padding: 2rem 0 2.5rem;
+  margin: 3rem var(--hd-gutter) 0;
+  padding: 2.5rem 0 2rem;
   border-top: 1px solid var(--hd-border);
 }
-.hd-site-footer__row {
+.hd-site-footer__top {
+  display: grid;
+  gap: 2.5rem;
+}
+.hd-site-footer__about {
+  display: grid;
+  align-content: start;
+  justify-items: start;
+  gap: 0.875rem;
+}
+.hd-site-footer__lede {
+  max-width: 22rem;
+  margin: 0;
+  color: var(--hd-muted-fg);
+  font-size: 0.875rem;
+  line-height: 1.55;
+}
+.hd-site-footer__columns {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 2rem 1.5rem;
+}
+.hd-site-footer__heading {
+  margin: 0 0 0.625rem;
+  color: var(--hd-fg);
+  font: 600 0.8125rem/1.3 var(--hd-font-heading);
+  letter-spacing: -0.005em;
+}
+.hd-site-footer__column ul {
+  display: grid;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.hd-site-footer__link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-height: 2rem;
+  color: var(--hd-muted-fg);
+  font-size: 0.875rem;
+  line-height: 1.35;
+  text-decoration: none;
+  transition: color 150ms ease;
+}
+.hd-site-footer__link:hover {
+  color: var(--hd-fg);
+}
+.hd-site-footer__link img {
+  flex-shrink: 0;
+  width: 1.125rem;
+  height: 1.125rem;
+}
+.hd-site-footer__bottom {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
   justify-content: space-between;
   gap: 1rem;
+  margin-top: 2.5rem;
 }
-.hd-site-footer__row--meta p {
-  max-width: 32rem;
+.hd-site-footer__legal {
   margin: 0;
   color: var(--hd-muted-fg);
-  font-size: 0.875rem;
-  line-height: 1.55;
+  font-size: 0.8125rem;
 }
 .hd-brand--footer {
   margin-inline-start: -0.5rem;
@@ -1837,6 +1914,21 @@ starlight-tabs [role="tabpanel"] {
 .hd-brand--footer .hd-brand__name {
   font-size: 0.9375rem;
 }
+/* Trois colonnes au plus tant que le produit est au-dessus : 3 + 2 plutôt que 4 + 1. */
+@media (min-width: 40em) {
+  .hd-site-footer__columns {
+    grid-template-columns: repeat(auto-fit, minmax(max(8.5rem, 30%), 1fr));
+  }
+}
+@media (min-width: 72em) {
+  .hd-site-footer__columns {
+    grid-template-columns: repeat(auto-fit, minmax(8.5rem, 1fr));
+  }
+  .hd-site-footer__top {
+    grid-template-columns: minmax(12rem, 15rem) minmax(0, 1fr);
+    gap: 3rem;
+  }
+}
 .hd-socials {
   display: flex;
   gap: 0.25rem;
@@ -2385,6 +2477,14 @@ hgdc-assistant::before {
 
 /* Cibles tactiles de 44 px au doigt, sans changer le dessin à la souris. */
 @media (pointer: coarse) {
+  .hd-pill,
+  .hd-site-footer__link {
+    min-height: 2.75rem;
+  }
+  .hd-theme-choice button {
+    width: 2.75rem;
+    height: 2.75rem;
+  }
   .hd-nav__link {
     min-height: 2.75rem;
   }