initial scaffolding for markdown services

.gitignore

@@ -1,3 +1,4 @@
+.run/**
 workshop/**
 local/**
 metrics/**

docsys/src/test/java/io/nosqlbench/docsys/core/DocsysMarkdownLoaderEndpointTest.java

@@ -2,7 +2,7 @@ package io.nosqlbench.docsys.core;
 
 import org.junit.Test;
 
-public class DocsysMarkdownEndpointTest {
+public class DocsysMarkdownLoaderEndpointTest {
 
     @Test
     public void testDocLoader() {

nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/DocScope.java

@@ -0,0 +1,32 @@
+package io.nosqlbench.nb.api.markdown.descriptor;
+
+/**
+ * DocScope determines which display mode a topic is meant to be displayed in.
+ * You should filter for the DocScopes you are interested in when you ask
+ * for markdown content.
+ *
+ * The special values ANY and NONE are provided for two reasons:
+ */
+public enum DocScope {
+
+    CommandLine(false),
+    StaticWeb(false),
+    DynamicWeb(false),
+    ANY(true),
+    NONE(true);
+
+    /**
+     * If a doc scope is marked as a query param, then it may only be used as a query param, or returned
+     * as a default or qualifier, but should not be assigned in content metadata.
+     * Content readers should throw an error when ANY or NONE are found in raw content.
+     * Content readers should add ANY to any content which contains any non-query scope.
+     * Content readers should add NONE to any content which contains no non-query scope.
+     *
+     * This is added to provide a uniform and simple query interface.
+     */
+    private final boolean queryParam;
+
+    DocScope(boolean queryParam) {
+        this.queryParam = queryParam;
+    }
+}

nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/FrontMatter.java

@@ -0,0 +1,75 @@
+package io.nosqlbench.nb.api.markdown.descriptor;
+
+import java.util.List;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * FrontMatter services provided within NoSQLBench are required to return the following types.
+ * If the markdown source file does not contain the metadata requested, then reasonable non-null
+ * defaults must be provided.
+ */
+public interface FrontMatter {
+    /**
+     * @return A title for the given markdown source file.
+     */
+    String getTitle();
+
+    /**
+     * @return A weight for the given markdown source file.
+     */
+    int getWeight();
+
+    /**
+     * <p>
+     * Topics in this service are taxonomically hierarchical, and use the same naming convention
+     * as relative file paths. (In a *NIX system, meaning forward slashes as path separators).
+     * </p>
+     *
+     * <p>
+     * The end name on a topic is considered the local topic name. The leading names before this
+     * local topic name are considered nested categories. Taken together, these categories
+     * (in hierarchic ordered form) are the <i>general category</i>.
+     * </p>
+     *
+     * <p>
+     * A topic and the location of the markdown content it is part of are <EM>NOT</EM> bound
+     * together.
+     * </p>
+     *
+     * @return A list of categories
+     */
+    List<String> getTopics();
+
+    /**
+     * <p>
+     * Aggregation patterns coalesce all the topics that they match into a seamless logical
+     * section of content. All source markdown files which have a topic which is matched
+     * by at least one of the aggregation patterns is included in the order of their weight.
+     * </p>
+     *
+     * <P>
+     * Aggregation patterns are simple regexes. It is possible to have multiple patterns as well
+     * as content that is referenced by multiple aggregations, from the same or different source
+     * aggregating topics.
+     * </P>
+     *
+     * @return A list of aggregation patterns
+     */
+    List<Pattern> getAggregations();
+
+    /**
+     * If a markdown source is flagged for use in a specific doc scope, then you can filter for
+     * that scope when you ask for markdown.
+     * <p>
+     * Markdown content which contains zero scopes should explicitly return {@link DocScope#NONE}.
+     * Markdown content which contains one or more scopes should explicitly add
+     * {@link DocScope#ANY} to the returned set.
+     * Markdown should never be tagged with ANY or NONE in the source content. Readers should throw
+     * an error if this is detected.
+     *
+     * @return A list of DocScopes for which this markdown should be used.
+     */
+    Set<DocScope> getDocScopes();
+
+}

nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/MarkdownInfo.java

@@ -0,0 +1,10 @@
+package io.nosqlbench.nb.api.markdown.descriptor;
+
+import java.nio.file.Path;
+
+public interface MarkdownInfo {
+    Path getPath();
+    CharSequence getBody();
+    FrontMatter getFrontmatter();
+
+}

nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/MarkdownProvider.java

@@ -0,0 +1,10 @@
+package io.nosqlbench.nb.api.markdown.descriptor;
+
+import java.util.List;
+
+/**
+ * A MarkdownProvider simply provides all the markdown content it is aware of.
+ */
+public interface MarkdownProvider {
+    List<MarkdownInfo> getMarkdownInfo();
+}

nb-api/src/main/java/io/nosqlbench/nb/api/markdown/finder/MarkdownLoader.java

@@ -0,0 +1,10 @@
+package io.nosqlbench.nb.api.markdown.finder;
+
+import io.nosqlbench.nb.api.markdown.descriptor.DocScope;
+import io.nosqlbench.nb.api.markdown.descriptor.MarkdownInfo;
+
+public class MarkdownLoader {
+    public static MarkdownInfo find(DocScope... scopes) {
+        DocSer
+    }
+}

nb-api/src/test/resources/testmarkdown/topics-a/entry1-1.md

@@ -0,0 +1,10 @@
+---
+title: Entry 1-1
+weight: 37
+topic: entries/entry1-1
+aggregate: topic
+---
+
+# Title Heading for Entry 1-1
+
+