semantic-release · babblebey · Jun 5, 2026 · Mar 24, 2026 · Mar 27, 2026 · Apr 6, 2026
diff --git a/astro.config.js b/astro.config.js
@@ -47,12 +47,22 @@ export default defineConfig({
           label: "Usage",
           items: [
             { slug: "usage/getting-started" },
-            { slug: "usage/installation" },
-            { slug: "usage/ci-configuration" },
             { slug: "usage/configuration" },
-            { slug: "usage/plugins" },
-            { slug: "usage/workflow-configuration" },
-            { slug: "usage/shareable-configurations" },
+            { slug: "usage/ci-configuration" },
+            { slug: "usage/running" },
+          ],
+        },
+        {
+          label: "Foundations",
+          items: [
+            { slug: "foundation", label: "Overview" },
+            { slug: "foundation/how-it-works" },
+            { slug: "foundation/release-steps" },
+            { slug: "foundation/considerations" },
+            { slug: "foundation/supported-branching" },
+            { slug: "foundation/workflow-configuration" },
+            { slug: "foundation/plugins" },
+            { slug: "foundation/shareable-configurations" },
           ],
         },
         {
@@ -68,25 +78,28 @@ export default defineConfig({
             {
               label: "CI Configurations",
               items: [
-                { slug: "recipes/ci-configurations" },
-                { slug: "recipes/ci-configurations/circleci-workflows" },
-                { slug: "recipes/ci-configurations/travis" },
-                { slug: "recipes/ci-configurations/gitlab-ci" },
+                { slug: "recipes/ci-configurations", label: "Overview" },
                 { slug: "recipes/ci-configurations/github-actions" },
+                { slug: "recipes/ci-configurations/gitlab-ci" },
+                {
+                  slug: "recipes/ci-configurations/circleci-workflows",
+                  label: "CircleCI Workflows",
+                },
+                { slug: "recipes/ci-configurations/travis" },
                 { slug: "recipes/ci-configurations/jenkins-ci" },
               ],
             },
             {
               label: "Git Hosted Services",
               items: [
-                { slug: "recipes/git-hosted-services" },
+                { slug: "recipes/git-hosted-services", label: "Overview" },
                 { slug: "recipes/git-hosted-services/git-auth-ssh-keys" },
               ],
             },
             {
               label: "Release Workflow",
               items: [
-                { slug: "recipes/release-workflow" },
+                { slug: "recipes/release-workflow", label: "Overview" },
                 { slug: "recipes/release-workflow/distribution-channels" },
                 { slug: "recipes/release-workflow/maintenance-releases" },
                 { slug: "recipes/release-workflow/pre-releases" },

diff --git a/src/components/PluginCard.astro b/src/components/PluginCard.astro
@@ -0,0 +1,181 @@
+---
+type PluginStep = {
+  verifyConditions?: string;
+  analyseCommits?: string;
+  verifyRelease?: string;
+  generateNotes?: string;
+  prepare?: string;
+  publish?: string;
+  addChannel?: string;
+  success?: string;
+  fail?: string;
+};
+
+interface Props {
+  name: string;
+  url: string;
+  description?: string;
+  steps?: PluginStep;
+}
+
+const { name, url, description, steps = {} } = Astro.props;
+const stepEntries = Object.entries(steps);
+---
+
+<article class="plugin-card">
+  <header class="plugin-card-header">
+    <h3 class="plugin-card-name">{name}</h3>
+    <a
+      href={url}
+      target="_blank"
+      rel="noopener noreferrer"
+      class="plugin-card-link"
+      aria-label={`View ${name}`}
+    >
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="18"
+        height="18"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
+        <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"
+        ></path>
+        <polyline points="15 3 21 3 21 9"></polyline>
+        <line x1="10" y1="14" x2="21" y2="3"></line>
+      </svg>
+    </a>
+  </header>
+  {description && <p class="plugin-card-description">{description}</p>}
+  {
+    stepEntries.length > 0 && (
+      <dl class="plugin-card-steps">
+        {stepEntries.map(([stepName, descriptionription]) => (
+          <details class="plugin-step">
+            <summary class="plugin-step-summary">
+              <dt class="plugin-step-name">{stepName}</dt>
+              <svg
+                class="plugin-step-chevron"
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <polyline points="6 9 12 15 18 9" />
+              </svg>
+            </summary>
+            <dd class="plugin-step-description" set:html={descriptionription} />
+          </details>
+        ))}
+      </dl>
+    )
+  }
+</article>
+
+<style>
+  .plugin-card {
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.25rem;
+    padding: 1.25rem;
+    transition: border-color 0.2s;
+    height: fit-content;
+    box-shadow: var(--sl-shadow-sm);
+    margin-top: 0;
+  }
+  .plugin-card:hover {
+    border-color: var(--sl-color-gray-300);
+  }
+  .plugin-card-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem;
+    margin-bottom: 0.5rem;
+  }
+  .plugin-card-name {
+    font-size: var(--sl-text-lg);
+    font-weight: 600;
+    color: var(--sl-color-white);
+    word-break: break-word;
+    margin: 0;
+  }
+  .plugin-card-link {
+    flex-shrink: 0;
+    color: var(--sl-color-gray-400);
+    transition: color 0.2s;
+  }
+  .plugin-card-link:hover {
+    color: var(--sl-color-white);
+  }
+  .plugin-card-description {
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-300);
+    margin: 0 0 0.75rem;
+    line-height: 1.5;
+  }
+  .plugin-card-steps {
+    display: flex;
+    flex-direction: column;
+    border-top: 1px solid var(--sl-color-gray-600);
+    margin: 0;
+    padding: 0;
+  }
+  .plugin-step {
+    border-bottom: 1px solid var(--sl-color-gray-600);
+  }
+  .plugin-step:last-child {
+    border-bottom: none;
+  }
+  .plugin-step-summary {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0.1rem 0;
+    cursor: pointer;
+    list-style: none;
+    user-select: none;
+    margin-bottom: 0;
+  }
+  .plugin-step-summary::-webkit-details-marker {
+    display: none;
+  }
+  .plugin-step-summary::marker {
+    display: none;
+    content: "";
+  }
+  .plugin-step-summary::before {
+    display: none !important;
+    content: none !important;
+  }
+  .plugin-step-name {
+    font-size: 0.9rem;
+    font-weight: 500;
+    color: var(--sl-color-white);
+    font-family: var(--sl-font-system-mono, ui-monospace, monospace);
+  }
+  .plugin-step-chevron {
+    flex-shrink: 0;
+    color: var(--sl-color-gray-400);
+    transition: transform 0.2s ease;
+    margin-top: 0;
+  }
+  .plugin-step[open] .plugin-step-chevron {
+    transform: rotate(180deg);
+  }
+  .plugin-step-description {
+    padding: 0 0 0.25rem;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-300);
+    line-height: 1.6;
+    margin: 0.25rem 0 0;
+  }
+</style>
diff --git a/src/content/docs/developer-guide/js-api.md b/src/content/docs/developer-guide/js-api.md
@@ -74,17 +74,17 @@ try {
 
 ### semanticRelease(\[options], \[config]) => Promise
 
-Run **semantic-release** and returns a `Promise` that resolves to a [Result](js-api.md#result) object.
+Run **semantic-release** and returns a `Promise` that resolves to a [Result](#result) object.
 
 #### options
 
 Type: `Object`
 
 **semantic-release** options.
 
-Can be used to set any [core option](../usage/configuration.md#configuration) or [plugin options](../usage/plugins.md#configuration).
+Can be used to set any [core option](/usage/configuration#option) or [plugin options](/usage/configuration/#plugins).
 
-Each option, will take precedence over options configured in the [configuration file](../usage/configuration.md#configuration) and [shareable configurations](../usage/configuration.md#extends).
+Each option, will take precedence over options configured in the [configuration file](/usage/configuration#configuration-file) and [shareable configurations](/usage/configuration#extends).
 
 #### config
 
@@ -132,7 +132,7 @@ It allows to configure **semantic-release** to write errors to a specific stream
 
 Type: `Object` `Boolean`<br>
 
-An object with [`lastRelease`](js-api.md#lastrelease), [`nextRelease`](js-api.md#nextrelease), [`commits`](js-api.md#commits) and [`releases`](js-api.md#releases) if a release is published or `false` if no release was published.
+An object with [`lastRelease`](#lastrelease), [`nextRelease`](#nextrelease), [`commits`](#commits) and [`releases`](#releases) if a release is published or `false` if no release was published.
 
 #### lastRelease