flow: links to markdowns via relative paths without depth restriction

znai-core/src/main/java/org/testingisdocumenting/znai/core/ComponentsRegistry.java

@@ -26,20 +26,20 @@
 import org.testingisdocumenting.znai.time.TimeService;
 
 /**
- * simple components registry to avoid introduction of DI frameworks.
+ * simple components registry to avoid a dependency on DI frameworks.
  * One place where we don't control dependencies passing is {@link IncludePlugin}
  *
  * @see IncludePlugin
  */
 public interface ComponentsRegistry {
     /**
-     * documentation wide default parser, can be markdown or any other parser that is used to build a documentation.
+     * documentation wide default parser: can be markdown or any other parser that is used to build documentation.
      * @return instance of a default parser
      */
     MarkupParser defaultParser();
 
     /**
-     * markdown specific parser
+     * markdown-specific parser
      * @return Markdown parser
      */
     MarkdownParser markdownParser();

znai-core/src/main/java/org/testingisdocumenting/znai/extensions/file/CodeReferencesFeature.java

@@ -79,7 +79,7 @@ private void validateLinks(DocReferences references) {
         references.pageUrlsStream().forEach(pageUrl ->
                 docStructure.validateUrl(markupPath,
                         "reference file name: " + referencesFullPath.getFileName().toString(),
-                        new DocUrl(markupPath, pageUrl))
+                        new DocUrl(pageUrl))
         );
     }
 

znai-core/src/main/java/org/testingisdocumenting/znai/parser/NoOpParserHandler.java

@@ -29,7 +29,6 @@
 import org.testingisdocumenting.znai.parser.table.MarkupTableData;
 import org.testingisdocumenting.znai.reference.DocReferences;
 
-import java.nio.file.Path;
 import java.util.Map;
 
 public class NoOpParserHandler implements ParserHandler {
@@ -138,7 +137,7 @@ public void onInlinedCode(String inlinedCode, DocReferences docReferences) {
     }
 
     @Override
-    public void onLinkStart(Path markupPath, String url) {
+    public void onLinkStart(String url) {
     }
 
     @Override

znai-core/src/main/java/org/testingisdocumenting/znai/parser/ParserHandler.java

@@ -29,7 +29,6 @@
 import org.testingisdocumenting.znai.parser.table.MarkupTableData;
 import org.testingisdocumenting.znai.reference.DocReferences;
 
-import java.nio.file.Path;
 import java.util.Map;
 
 /**
@@ -72,7 +71,7 @@ public interface ParserHandler {
     void onBlockQuoteEnd();
     void onSimpleText(String value);
     void onInlinedCode(String inlinedCode, DocReferences docReferences);
-    void onLinkStart(Path markupPath, String url);
+    void onLinkStart(String url);
     void onLinkEnd();
     void onImage(String title, String destination, String alt);
     void onSnippet(PluginParams pluginParams, String lang, String lineNumber, String snippet);

znai-core/src/main/java/org/testingisdocumenting/znai/parser/ParserHandlersList.java

@@ -29,7 +29,6 @@
 import org.testingisdocumenting.znai.parser.table.MarkupTableData;
 import org.testingisdocumenting.znai.reference.DocReferences;
 
-import java.nio.file.Path;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
@@ -172,8 +171,8 @@ public void onInlinedCode(String inlinedCode, DocReferences docReferences) {
     }
 
     @Override
-    public void onLinkStart(Path markupPath, String url) {
-        list.forEach(h -> h.onLinkStart(markupPath, url));
+    public void onLinkStart(String url) {
+        list.forEach(h -> h.onLinkStart(url));
     }
 
     @Override

znai-core/src/main/java/org/testingisdocumenting/znai/parser/commonmark/MarkdownVisitor.java

@@ -216,7 +216,7 @@ public void visit(FencedCodeBlock fencedCodeBlock) {
 
     @Override
     public void visit(Link link) {
-        parserHandler.onLinkStart(path, link.getDestination());
+        parserHandler.onLinkStart(link.getDestination());
         visitChildren(link);
         parserHandler.onLinkEnd();
     }

znai-core/src/main/java/org/testingisdocumenting/znai/parser/docelement/DocElementCreationParserHandler.java

@@ -39,10 +39,7 @@
 import org.testingisdocumenting.znai.parser.table.MarkupTableData;
 import org.testingisdocumenting.znai.reference.DocReferences;
 import org.testingisdocumenting.znai.resources.ResourcesResolver;
-import org.testingisdocumenting.znai.structure.AnchorIds;
-import org.testingisdocumenting.znai.structure.DocStructure;
-import org.testingisdocumenting.znai.structure.DocUrl;
-import org.testingisdocumenting.znai.structure.TocItem;
+import org.testingisdocumenting.znai.structure.*;
 import org.testingisdocumenting.znai.utils.StringUtils;
 import org.testingisdocumenting.znai.utils.UrlUtils;
 
@@ -294,8 +291,8 @@ public void onInlinedCode(String inlinedCode, DocReferences docReferences) {
     }
 
     @Override
-    public void onLinkStart(Path markupPath, String url) {
-        DocUrl docUrl = new DocUrl(markupPath, url);
+    public void onLinkStart(String url) {
+        DocUrl docUrl = new DocUrl(url);
 
         boolean isFile = isLocalFile(docUrl, url);
         String convertedUrl = isFile ?
@@ -337,7 +334,8 @@ public void onImage(String title, String destination, String alt) {
 
             auxiliaryFiles.add(auxiliaryFile);
         } else {
-            docStructure.validateUrl(path, "![]() image", new DocUrl(path, destination));
+            docStructure.validateUrl(path, "![]() image",
+                    new DocUrl(destination));
             append(DocElementType.IMAGE, "title", title,
                     "destination", destination,
                     "alt", alt,
@@ -420,7 +418,7 @@ public void onGlobalAnchor(String id) {
     @Override
     public void onGlobalAnchorRefStart(String id) {
         String anchorUrl = componentsRegistry.docStructure().globalAnchorUrl(path, id);
-        onLinkStart(path, anchorUrl);
+        onLinkStart(anchorUrl);
     }
 
     @Override
@@ -548,6 +546,10 @@ private boolean isLocalFile(DocUrl docUrl, String url) {
             return false;
         }
 
+        if (docUrl.isFilePathBased()) {
+            return false;
+        }
+
         TocItem tocItem = componentsRegistry.docStructure().tableOfContents().findTocItem(docUrl.getDirName(), docUrl.getFileNameWithoutExtension());
         if (tocItem != null) {
             return false;
@@ -596,7 +598,7 @@ public void visit(Text text) {
 
             @Override
             public void visit(Link link) {
-                parserHandler.onLinkStart(path, link.getDestination());
+                parserHandler.onLinkStart(link.getDestination());
                 visitChildren(link);
                 parserHandler.onLinkEnd();
             }

znai-core/src/main/java/org/testingisdocumenting/znai/reference/GlobalDocReferences.java

@@ -66,7 +66,7 @@ private void validateLinks() {
         DocStructure docStructure = componentsRegistry.docStructure();
 
         docReferences.pageUrlsStream().forEach(pageUrl ->
-                docStructure.validateUrl(globalReferencesPathNoExt, "", new DocUrl(globalReferencesPathNoExt, pageUrl)));
+                docStructure.validateUrl(globalReferencesPathNoExt, "", new DocUrl(pageUrl)));
     }
 
     public Path getGlobalReferencesPathNoExt() {

znai-core/src/main/java/org/testingisdocumenting/znai/structure/DocUrl.java

@@ -19,23 +19,23 @@
 import org.testingisdocumenting.znai.utils.FilePathUtils;
 import org.testingisdocumenting.znai.utils.UrlUtils;
 
-import java.nio.file.Path;
-
 public class DocUrl {
     private static final String LINK_TO_SECTION_INSTRUCTION = """
             To refer to a section of a document page use either
               dir-name/file-name-without-extension#page-section-id or
-              ../dir-name/file-name.md#page-section-id or
-              ./file-name-within-chapter.md#page-section-id
               (#page-section-id is optional)
             dir-name is not an arbitrary directory name or structure, but the TOC directory associated with a chapter
             Use #page-section-id to refer to the current page section.
             Use /#section-id to refer the root page of a documentation.
+
+            Alternatively you can use a relative path to another markdown file.
+            Path can be relative to the root of the documentation or to the current file.
             """;
 
     private String dirName = "";
     private String fileNameWithoutExtension = "";
     private String anchorId = "";
+    private String tocItemFilePath = "";
 
     private String url;
 
@@ -57,13 +57,15 @@ public DocUrl(String dirName, String fileNameWithoutExtension, String anchorId)
         this.anchorId = anchorId;
     }
 
-    public DocUrl(Path markupPath, String url) {
+    public DocUrl(String url) {
         this.url = url;
 
         boolean handled = handleExternal() ||
+                handleBasedOnFilePath(url) ||
+                handleLocalFile(url) ||
                 handleIndex() ||
                 handleAnchorOnly() ||
-                handleLocal(markupPath);
+                handleLocal();
 
         if (!handled) {
             throw new IllegalStateException("couldn't parse url: " + url);
@@ -74,6 +76,23 @@ private boolean handleExternal() {
         return isExternalUrl = UrlUtils.isExternal(url);
     }
 
+    private boolean handleLocalFile(String url) {
+        return !FilePathUtils.fileExtension(url).isEmpty();
+    }
+
+    private boolean handleBasedOnFilePath(String url) {
+        String withoutAnchor = UrlUtils.removeAnchor(url);
+        String extension = FilePathUtils.fileExtension(withoutAnchor);
+
+        if (extension.startsWith("md")) {
+            tocItemFilePath = withoutAnchor;
+            anchorId = UrlUtils.extractAnchor(url);
+            return true;
+        }
+
+        return false;
+    }
+
     private boolean handleIndex() {
         if (url.startsWith("/#")) {
             isIndexUrl = true;
@@ -96,24 +115,20 @@ private boolean handleAnchorOnly() {
         return isAnchorOnly;
     }
 
-    private boolean handleLocal(Path markupPath) {
+    private boolean handleLocal() {
         String[] parts = url.split("/");
-        if (parts.length == 1) {
-            return handleNoDirSpecified(markupPath, parts[0]);
-        }
-
         if (parts.length != 2 && parts.length != 3) {
-            throwUnexpectedPattern(url);
+            throw new IllegalArgumentException("Unexpected url pattern: <" + url + "> " + LINK_TO_SECTION_INSTRUCTION);
         }
 
-        if (parts.length == 3 && !parts[0].equals("..") && !parts[0].equals(".")) {
-            throwUnexpectedPattern(url);
+        if (parts.length == 3 && !parts[0].equals("..")) {
+            throw new IllegalArgumentException("Unexpected url pattern: <" + url + "> " + LINK_TO_SECTION_INSTRUCTION);
         }
 
         int dirIdx = parts.length == 3 ? 1 : 0;
         int nameIdx = parts.length == 3 ? 2 : 1;
 
-        dirName = replaceDirNameIfRequired(markupPath, parts[dirIdx]);
+        dirName = parts[dirIdx];
 
         int idxOfAnchorSep = parts[nameIdx].indexOf('#');
 
@@ -123,28 +138,6 @@ private boolean handleLocal(Path markupPath) {
         return true;
     }
 
-    private void throwUnexpectedPattern(String url) {
-        throw new IllegalArgumentException("Unexpected url pattern: <" + url + "> " + LINK_TO_SECTION_INSTRUCTION);
-    }
-
-    private boolean handleNoDirSpecified(Path markupPath, String part) {
-        int idxOfAnchorSep = part.indexOf('#');
-        dirName = replaceDirNameIfRequired(markupPath, "");
-        fileNameWithoutExtension = FilePathUtils.fileNameWithoutExtension(idxOfAnchorSep == -1 ? part : part.substring(0, idxOfAnchorSep));
-        anchorId = idxOfAnchorSep == -1 ? "" : part.substring(idxOfAnchorSep + 1);
-
-        return true;
-    }
-
-    private static String replaceDirNameIfRequired(Path markupPath, String currentDirName) {
-        if (currentDirName.equals(".") || currentDirName.isEmpty()) {
-            Path parentPath = markupPath.getParent();
-            return parentPath != null ? parentPath.getFileName().toString() : "";
-        } else {
-            return currentDirName;
-        }
-    }
-
     public boolean isIndexUrl() {
         return isIndexUrl;
     }
@@ -157,6 +150,20 @@ public boolean isAnchorOnly() {
         return isAnchorOnly;
     }
 
+    public boolean isFilePathBased() {
+        return !tocItemFilePath.isEmpty();
+    }
+
+    public String getTocItemFilePath() {
+        return tocItemFilePath;
+    }
+
+    public void setResolvedToDirNameAndFileName(String dirName, String fileNameWithoutExtension) {
+        this.tocItemFilePath = "";
+        this.dirName = dirName;
+        this.fileNameWithoutExtension = fileNameWithoutExtension;
+    }
+
     public String getDirName() {
         return dirName;
     }

znai-core/src/main/java/org/testingisdocumenting/znai/structure/TocItem.java

@@ -90,7 +90,8 @@ public String getFilePath() {
             return getDirName() + "/" + path;
         }
 
-        return getDirName() + "/" + getFileNameWithoutExtension() + "." + getFileExtension();
+        return getDirName() + "/" + getFileNameWithoutExtension() +
+                (getFileExtension().isEmpty() ? "" : "." + getFileExtension());
     }
 
     public String getFileExtension() {

znai-core/src/test/groovy/org/testingisdocumenting/znai/parser/MarkdownParserTest.groovy

@@ -81,15 +81,17 @@ class MarkdownParserTest {
     @Test
     void "link to an existing within documentation location"() {
         componentsRegistry.docStructure().addValidLink("valid-dir-name/page-name")
+        componentsRegistry.docStructure().addValidLink("../valid-dir-name/page-name.md")
         componentsRegistry.docStructure().addValidLink("valid-dir-name/page-name#page-section")
+        componentsRegistry.docStructure().addValidLink("../valid-dir-name/page-name.md#page-section")
 
         parse("[label](valid-dir-name/page-name)")
         content.should == [[type: 'Paragraph', content:[[url: '/test-doc/valid-dir-name/page-name', isFile: false,
                                                          type: 'Link',
                                                          content:[[text: 'label' , type: 'SimpleText']]]]]]
 
         parse("[label](../valid-dir-name/page-name.md)")
-        content.should == [[type: 'Paragraph', content:[[url: '/test-doc/valid-dir-name/page-name', isFile: false,
+        content.should == [[type: 'Paragraph', content:[[url: 'resolved-url-for:../valid-dir-name/page-name.md', isFile: false,
                                                          type: 'Link',
                                                          content:[[text: 'label' , type: 'SimpleText']]]]]]
 
@@ -98,17 +100,18 @@ class MarkdownParserTest {
                                                          isFile: false, type: 'Link',
                                                          content:[[text: 'label' , type: 'SimpleText']]]]]]
 
-        parse("[label](../valid-dir-name/page-name#page-section)")
-        content.should == [[type: 'Paragraph', content:[[url: '/test-doc/valid-dir-name/page-name#page-section',
+        parse("[label](../valid-dir-name/page-name.md#page-section)")
+        content.should == [[type: 'Paragraph', content:[[url: 'resolved-url-for:../valid-dir-name/page-name.md#page-section',
                                                          isFile: false, type: 'Link',
                                                          content:[[text: 'label' , type: 'SimpleText']]]]]]
     }
 
     @Test
     void "link to a markdown file within a current directory"() {
-        componentsRegistry.docStructure().addValidLink("valid-dir-name/page-three")
-        parse("[page 3](page-three.md)", Paths.get("valid-dir-name/page-two.md"))
-        content.should == [[type: 'Paragraph', content:[[url: '/test-doc/valid-dir-name/page-three', isFile: false,
+        componentsRegistry.docStructure().addValidLink("page-three.md")
+
+        parse("[page 3](page-three.md)", Paths.get("page-two/page-two.md"))
+        content.should == [[type: 'Paragraph', content:[[url: 'resolved-url-for:page-three.md', isFile: false,
                                                          type: 'Link',
                                                          content:[[text: 'page 3' , type: 'SimpleText']]]]]]
     }

znai-core/src/test/groovy/org/testingisdocumenting/znai/parser/TestComponentsRegistry.groovy

@@ -40,6 +40,8 @@ class TestComponentsRegistry implements ComponentsRegistry {
     private MarkupParser markdownParser = new TestMarkdownParser(this)
     private MarkupParser defaultParser = new TestMarkupParser()
 
+    private TestResourceResolver resourceResolver = new TestResourceResolver(Paths.get(""))
+
     private GlobalAssetsRegistry assetsRegistry = new GlobalAssetsRegistry()
     private TimeService timeService = new FakeTimeService()
 
@@ -75,7 +77,11 @@ class TestComponentsRegistry implements ComponentsRegistry {
 
     @Override
     ResourcesResolver resourceResolver() {
-        return new TestResourceResolver(Paths.get(""))
+        return resourceResolver
+    }
+
+    void setResourceResolver(TestResourceResolver resourceResolver) {
+        this.resourceResolver = resourceResolver
     }
 
     @Override