refactor(docs): link the edition registry from the landing page statically

Replace the generated per-edition link list on docs/index.md with a
static sentence pointing at the generated registry index, and drop the
now-unused marker-splicing machinery from the generator: it only writes
docs/specs/editions/ now.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XKRaAHmFNvb7JoKTJVW8Pw
Signed-off-by: Claude <noreply@anthropic.com>

Author: claude

docs/index.md

@@ -94,14 +94,8 @@ internals. Build and benchmark locally.
 ## Editions
 
 Vortex writers target **[editions](specs/editions.md)** — named, frozen sets of encodings that
-carry a forever read-compatibility guarantee:
-
-<!-- BEGIN generated edition links: edit the declarations in `vortex/src/editions/` and run `cargo xtask generate-editions-docs` -->
-
-- **core**: [`core2025.05.0`](specs/editions/core2025.05.0.md) · [`core2025.06.0`](specs/editions/core2025.06.0.md) · [`core2025.10.0`](specs/editions/core2025.10.0.md) · [`core2026.07.0`](specs/editions/core2026.07.0.md)
-- **unstable**: [`unstable2025.05.0`](specs/editions/unstable2025.05.0.md) · [`unstable2026.02.0`](specs/editions/unstable2026.02.0.md) · [`unstable2026.04.0`](specs/editions/unstable2026.04.0.md) · [`unstable2026.06.0`](specs/editions/unstable2026.06.0.md)
-
-<!-- END generated edition links -->
+carry a forever read-compatibility guarantee. See every edition in the
+[edition registry](specs/editions/index.md).
 
 ```{toctree}
 ---

xtask/README.md

@@ -22,15 +22,13 @@ be run every time changes are made to one of the .fbs files, or if any are added
 ### `generate-editions-docs`
 
 This regenerates the edition registry pages under `docs/specs/editions/` — an `index.md`
-listing every edition plus one page per edition — and the per-edition links on the docs
-landing page (`docs/index.md`) from the edition declarations in `vortex/src/editions/`.
-It first dumps the declarations as a TOML manifest to `target/editions-manifest.toml`
-(a build artifact, never committed) by running the `editions_manifest` example of the
-`vortex` crate, then renders that manifest into the registry pages (replacing the whole
-directory) and into the markdown between the `BEGIN`/`END generated edition links`
-markers on the landing page. The static spec, `docs/specs/editions.md`, links to the
-generated registry. Run it every time an edition declaration changes; CI fails if the
-committed registry is stale.
+listing every edition plus one page per edition — from the edition declarations in
+`vortex/src/editions/`. It first dumps the declarations as a TOML manifest to
+`target/editions-manifest.toml` (a build artifact, never committed) by running the
+`editions_manifest` example of the `vortex` crate, then renders that manifest into the
+registry pages, replacing the whole directory. The static pages (`docs/specs/editions.md`
+and the docs landing page) link to the generated registry. Run it every time an edition
+declaration changes; CI fails if the committed registry is stale.
 
 
 

xtask/src/generate_editions_docs.rs

@@ -4,21 +4,13 @@
 use std::collections::BTreeMap;
 use std::fmt::Write as _;
 use std::fs;
-use std::path::Path;
 use std::path::PathBuf;
 
 use anyhow::Context;
-use anyhow::bail;
 use serde::Deserialize;
 use xshell::Shell;
 use xshell::cmd;
 
-/// Marker lines delimiting the generated edition links on the docs landing page.
-/// Everything between them is owned by this generator; hand edits there are overwritten.
-static INDEX_BEGIN_MARKER: &str = "<!-- BEGIN generated edition links: edit the declarations in \
-                                   `vortex/src/editions/` and run `cargo xtask generate-editions-docs` -->";
-static INDEX_END_MARKER: &str = "<!-- END generated edition links -->";
-
 /// Header comment stamped on every fully generated page.
 static GENERATED_HEADER: &str = "<!-- Generated by `cargo xtask generate-editions-docs` from the \
                                  declarations in `vortex/src/editions/`; do not edit. -->";
@@ -62,16 +54,11 @@ impl ManifestEdition {
     fn sibling_link(&self) -> String {
         format!("[`{}`]({})", self.id, self.file_name())
     }
-
-    /// A link to this edition's page from `docs/index.md`.
-    fn landing_link(&self) -> String {
-        format!("[`{}`](specs/editions/{})", self.id, self.file_name())
-    }
 }
 
 /// Regenerate the edition registry pages under `docs/specs/editions/` (an index page plus
-/// one page per edition) and the edition links on `docs/index.md`, from the edition
-/// declarations in the `vortex` crate, via a TOML manifest written under `target/`.
+/// one page per edition) from the edition declarations in the `vortex` crate, via a TOML
+/// manifest written under `target/`.
 pub fn generate_editions_docs(profile: Option<String>) -> anyhow::Result<()> {
     let sh = Shell::new()?;
     let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("..");
@@ -125,40 +112,6 @@ pub fn generate_editions_docs(profile: Option<String>) -> anyhow::Result<()> {
         registry_dir.display()
     );
 
-    splice(
-        &root.join("docs/index.md"),
-        INDEX_BEGIN_MARKER,
-        INDEX_END_MARKER,
-        &render_landing_links(&manifest)?,
-    )?;
-    Ok(())
-}
-
-/// Replace the content between the marker comments in `path` with `content`.
-fn splice(path: &Path, begin_marker: &str, end_marker: &str, content: &str) -> anyhow::Result<()> {
-    let text = fs::read_to_string(path)?;
-    let (Some(begin), Some(end)) = (text.find(begin_marker), text.find(end_marker)) else {
-        bail!(
-            "{} must contain the generated-section BEGIN/END marker comments",
-            path.display()
-        );
-    };
-    if end < begin {
-        bail!(
-            "generated-section markers are out of order in {}",
-            path.display()
-        );
-    }
-
-    let mut spliced = String::new();
-    spliced.push_str(&text[..begin + begin_marker.len()]);
-    spliced.push_str("\n\n");
-    spliced.push_str(content);
-    spliced.push('\n');
-    spliced.push_str(&text[end..]);
-    fs::write(path, spliced)?;
-
-    println!("regenerated the edition links in {}", path.display());
     Ok(())
 }
 
@@ -277,26 +230,3 @@ fn render_edition(
     }
     Ok(md)
 }
-
-/// Render the per-family edition links that go between the markers in `docs/index.md`.
-fn render_landing_links(manifest: &Manifest) -> anyhow::Result<String> {
-    let mut md = String::new();
-    // Editions arrive sorted by family, so consecutive dedup yields each family once.
-    let mut families: Vec<&str> = manifest
-        .editions
-        .iter()
-        .map(|edition| edition.family.as_str())
-        .collect();
-    families.dedup();
-
-    for family in families {
-        let links: Vec<String> = manifest
-            .editions
-            .iter()
-            .filter(|edition| edition.family == family)
-            .map(ManifestEdition::landing_link)
-            .collect();
-        writeln!(md, "- **{family}**: {}", links.join(" · "))?;
-    }
-    Ok(md)
-}