flow: page-redirects.csv support

znai-cli/src/main/java/org/testingisdocumenting/znai/cli/ZnaiCliApp.java

@@ -179,6 +179,7 @@ private WebSite generateDocs(Path sourceRoot) {
                 withAdditionalLookupPaths(config.getLookupPaths()).
                 withFooterPath(sourceRoot.resolve("footer.md")).
                 withExtensionsDefPath(sourceRoot.resolve("extensions.json")).
+                withRedirectsPath(sourceRoot.resolve("page-redirects.csv")).
                 withGlobalReferencesPathNoExt(sourceRoot.resolve("references")).
                 withGlobalPluginParamsPath(sourceRoot.resolve(PLUGIN_PARAMS_FILE_NAME)).
                 withWebResources(favIconResource).

znai-docs/znai/release-notes/1.81/add-2025-10-19-page-redirects.md

@@ -0,0 +1 @@
+* Add: `page-redirects.csv` support to help with page renames

znai-tests/src/test/groovy/pages/PreviewServer.groovy

@@ -22,4 +22,8 @@ class PreviewServer {
     void openPreview(port) {
         browser.open("http://localhost:${port}/preview")
     }
+
+    void openPreviewWithUrl(port, url) {
+        browser.open("http://localhost:${port}/preview/${url}")
+    }
 }

znai-tests/src/test/groovy/sampledoc/page-redirects.csv

@@ -0,0 +1 @@
+chapter-three/page-one,chapter-one/links

znai-tests/src/test/groovy/scenarios/sampleDoc.groovy

@@ -40,6 +40,11 @@ scenario("validate page outside of chapter") {
     docContent.paragraphs.get("Files don't have to belong to chapters if you have simple docs").waitTo visible
 }
 
+scenario("check redirect page") {
+    previewServer.openPreviewWithUrl(port, "chapter-three/page-one")
+    docContent.title.waitToBe == "Links"
+}
+
 scenario("validate uploads files") {
     def baseUrl = "http://localhost:$port/preview"
 

znai-website-gen/src/main/java/org/testingisdocumenting/znai/website/PageRedirects.java

@@ -0,0 +1,87 @@
+package org.testingisdocumenting.znai.website;
+
+import org.testingisdocumenting.znai.html.Deployer;
+import org.testingisdocumenting.znai.parser.table.CsvTableParser;
+import org.testingisdocumenting.znai.parser.table.MarkupTableData;
+import org.testingisdocumenting.znai.structure.DocStructure;
+import org.testingisdocumenting.znai.structure.TocItem;
+import org.testingisdocumenting.znai.utils.FileUtils;
+import org.testingisdocumenting.znai.utils.ResourceUtils;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.stream.Collectors;
+
+
+public class PageRedirects {
+    private final Deployer deployer;
+    private final Path csvPath;
+    private final DocStructure docStructure;
+
+    public record FromTo (String oldLink, String newDirName, String newFileNameWithoutExtension) {}
+
+    public PageRedirects(DocStructure docStructure, Deployer deployer, Path csvPath) {
+        this.docStructure = docStructure;
+        this.deployer = deployer;
+        this.csvPath = csvPath;
+    }
+
+    public boolean isPresent() {
+        return Files.exists(csvPath);
+    }
+
+    public void deployRedirectPages() {
+        List<FromTo> redirects = parse(csvPath);
+        redirects.forEach(this::deployRedirect);
+    }
+
+    private void deployRedirect(FromTo fromTo) {
+        TocItem tocItem = docStructure.tableOfContents().findTocItem(fromTo.newDirName, fromTo.newFileNameWithoutExtension);
+        if (tocItem == null) {
+            throw new RuntimeException("toc item not found: " +
+                    fromTo.newDirName + "/" + fromTo.newFileNameWithoutExtension);
+        }
+
+        String redirectUrl = docStructure.fullUrl(
+                tocItem.getDirName() + "/" + tocItem.getFileNameWithoutExtension());
+        String redirectPage = ResourceUtils.textContent("template/redirect.html")
+                .replace("${newUrl}", redirectUrl);
+        deployer.deploy(fromTo.oldLink + "/index.html", redirectPage);
+    }
+
+    private static List<FromTo> parse(Path csvPath) {
+        return parse(FileUtils.fileTextContent(csvPath));
+    }
+
+    protected static List<FromTo> parse(String content) {
+        String withoutComments = Arrays.stream(content.split("\n"))
+                .filter(line -> !line.startsWith("#"))
+                .collect(Collectors.joining("\n"));
+
+        MarkupTableData tableData = CsvTableParser.parseWithHeader(withoutComments, "reference", "url");
+
+        List<FromTo> result = new ArrayList<>();
+        tableData.forEachRow(row -> {
+            String newUrl = row.get(1).toString();
+            String[] parts = newUrl.split("/");
+            String newDirName;
+            String newFileNameWithoutExtension;
+            if (parts.length == 1) {
+                newDirName = "";
+                newFileNameWithoutExtension = parts[0];
+            } else if (parts.length == 2) {
+                newDirName = parts[0];
+                newFileNameWithoutExtension = parts[1];
+            } else {
+                throw new RuntimeException("invalid url format, expected [dirName/]fileName");
+            }
+
+            result.add(new FromTo(row.get(0), newDirName, newFileNameWithoutExtension));
+        });
+
+        return result;
+    }
+}

znai-website-gen/src/main/java/org/testingisdocumenting/znai/website/WebSite.java

@@ -202,6 +202,7 @@ public void deploy() {
         reportPhase("deploying documentation");
         generatePages();
         generateChapterIndexRedirectPages();
+        generatePageRedirects();
         generateSearchIndex();
         generateLlmContent();
         deployToc();
@@ -652,6 +653,16 @@ private void generateChapterIndexRedirectPages() {
         });
     }
 
+    private void generatePageRedirects() {
+        PageRedirects pageRedirects = new PageRedirects(docStructure, deployer, cfg.redirectsPaths);
+        if (!pageRedirects.isPresent()) {
+            return;
+        }
+
+        reportPhase("generating page redirects");
+        pageRedirects.deployRedirectPages();
+    }
+
     private void generateSearchIndex() {
         reportPhase("generating search index");
 
@@ -940,6 +951,7 @@ public static class Configuration {
         private Path docRootPath;
         private Path footerPath;
         private Path extensionsDefPath;
+        private Path redirectsPaths;
         private Path globalReferencesPathNoExt;
         private Path pluginParamsPath;
         private final List<WebResource> webResources;
@@ -980,6 +992,11 @@ public Configuration withExtensionsDefPath(Path path) {
             return this;
         }
 
+        public Configuration withRedirectsPath(Path path) {
+            redirectsPaths = path.toAbsolutePath();
+            return this;
+        }
+
         public Configuration withGlobalReferencesPathNoExt(Path path) {
             globalReferencesPathNoExt = path.toAbsolutePath();
             return this;

znai-website-gen/src/test/groovy/org/testingisdocumenting/znai/website/PageRedirectsTest.groovy

@@ -0,0 +1,27 @@
+package org.testingisdocumenting.znai.website
+
+import org.junit.Test
+
+import static org.testingisdocumenting.webtau.WebTauCore.*
+
+class PageRedirectsTest {
+    @Test
+    void "parse redirects"() {
+        def result = PageRedirects.parse("""# optional comment
+old-chapter/old-page,new-chapter/new-page
+old-chapter/old-page-two,top-level-new-page
+""")
+        result.should == [                 "oldLink" |  "newDirName" | "newFileNameWithoutExtension"] {
+                        __________________________________________________________________________
+                              "old-chapter/old-page" | "new-chapter" | "new-page"
+                          "old-chapter/old-page-two" | ""            | "top-level-new-page" }
+    }
+
+    @Test
+    void "validation checks"() {
+        code {
+            PageRedirects.parse("""# optional comment
+old-chapter/old-page,new-chapter/new-page/sub-page
+""") } should throwException("invalid url format, expected [dirName/]fileName")
+    }
+}