diff --git a/.gitignore b/.gitignore
index 94bfba416..0b2558299 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+.run/**
workshop/**
local/**
metrics/**
diff --git a/docsys/src/test/java/io/nosqlbench/docsys/core/DocsysMarkdownEndpointTest.java b/docsys/src/test/java/io/nosqlbench/docsys/core/DocsysMarkdownLoaderEndpointTest.java
similarity index 83%
rename from docsys/src/test/java/io/nosqlbench/docsys/core/DocsysMarkdownEndpointTest.java
rename to docsys/src/test/java/io/nosqlbench/docsys/core/DocsysMarkdownLoaderEndpointTest.java
index 607551a54..908d6cd34 100644
--- a/docsys/src/test/java/io/nosqlbench/docsys/core/DocsysMarkdownEndpointTest.java
+++ b/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() {
diff --git a/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/DocScope.java b/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/DocScope.java
new file mode 100644
index 000000000..3a114e8a7
--- /dev/null
+++ b/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;
+ }
+}
diff --git a/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/FrontMatter.java b/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/FrontMatter.java
new file mode 100644
index 000000000..0a3607c45
--- /dev/null
+++ b/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();
+
+ /**
+ *
+ * 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).
+ *
+ *
+ *
+ * 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 general category.
+ *
+ *
+ *
+ * A topic and the location of the markdown content it is part of are NOT bound
+ * together.
+ *
+ *
+ * @return A list of categories
+ */
+ List getTopics();
+
+ /**
+ *
+ * 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.
+ *
+ *
+ *
+ * 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.
+ *
+ *
+ * @return A list of aggregation patterns
+ */
+ List 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.
+ *
+ * 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 getDocScopes();
+
+}
diff --git a/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/MarkdownInfo.java b/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/MarkdownInfo.java
new file mode 100644
index 000000000..94b6e4597
--- /dev/null
+++ b/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();
+
+}
diff --git a/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/MarkdownProvider.java b/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/descriptor/MarkdownProvider.java
new file mode 100644
index 000000000..b91469e3f
--- /dev/null
+++ b/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 getMarkdownInfo();
+}
diff --git a/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/finder/MarkdownLoader.java b/nb-api/src/main/java/io/nosqlbench/nb/api/markdown/finder/MarkdownLoader.java
new file mode 100644
index 000000000..189c71f01
--- /dev/null
+++ b/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
+ }
+}
diff --git a/nb-api/src/test/resources/testmarkdown/topics-a/entry1-1.md b/nb-api/src/test/resources/testmarkdown/topics-a/entry1-1.md
new file mode 100644
index 000000000..4d5a2c8c9
--- /dev/null
+++ b/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
+
+