To reduce documentation maintenance burden avoid copy and paste of code snippets. Embed content by referencing existing files using the plugin instead. This syntax will appear throughout the documentation and represents a family of custom Markdown extensions. The file will be looked up using following rules: directory with a markup file root directory of a documentation all lookup paths listed in a file include-file :include-file: file-name.js include- class JsClass { constructor() { usefulAction(); } } export default JsClass; lookup-paths

Syntax highlighting is automatically selected based file extension. E.g. extensions , , , are treated as C++. Use to force a different syntax highlighting Note: File extensions and are case-insensitive. .c .h .cpp .hpp :include-file: simple.c #include <iostream> using namespace std; int main() { cout << "hello"; } :include-file: Hello.sc object Hello { def main(args: Array[String]) = { println("Hello, world") } } lang :include-file: simple.c {lang: "java"} #include <iostream> using namespace std; int main() { cout << "hello"; } lang

Use the property to specify a title. Use the property to set to be the file name. :include-file: file-name.js {title: "ES6 class"} title class JsClass { constructor() { usefulAction(); } } export default JsClass; autoTitle title :include-file: file-name.js {autoTitle: true} class JsClass { constructor() { usefulAction(); } } export default JsClass;

When you specify a title, hover mouse over it to see a clickable anchor. Use to override auto generated identifier. anchorId :include-file: file-name.js {autoTitle: true, anchorId: "my-code-anchor"} class JsClass { constructor() { usefulAction(); } } export default JsClass;

Use the option to stretch wide code to occupy as much horizontal screen real estate as possible. Note: Good placement of a Wide Code element is at the end of a page or a section to show the full version of a code sample. wide :include-file: WideCode.java {wide: true, title: "wide code"} class InternationalPriceService implements PriceService { private static void LongJavaInterfaceNameWithSuperFactory createMegaAbstractFactory(final ExchangeCalendarLongerThanLife calendar) { ... } }

Use the option to enable long lines wrapping. wrap :include-file: WideCode.java {wrap: true} class InternationalPriceService implements PriceService { private static void LongJavaInterfaceNameWithSuperFactory createMegaAbstractFactory(final ExchangeCalendarLongerThanLife calendar) { ... } }

If you have a file with large code snippet and you want to initially display only a small fraction use option with an optional option to specify a number of initial lines displayed (default is 8). readMore readMoreVisibleLines :include-file: LongFile.java {readMore: true, readMoreVisibleLines: 3} public class DocScaffolding { private final Path workingDir; private Map<String, List<String>> fileNameByDirName; public DocScaffolding(Path workingDir) { this.workingDir = workingDir; this.fileNameByDirName = new LinkedHashMap<>(); } public void create() { createPages(); createToc(); createMeta(); createIndex(); createLookupPaths(); } private void createLookupPaths() { createFileFromResource("lookup-paths"); } private void createMeta() { createFileFromResource("meta.json"); } }

Use to make code snippet collapsible. Note: option is required collapsed: true|false title :include-file: file-name.js {title: "collapsible snippet", collapsed: true} class JsClass { constructor() { usefulAction(); } } export default JsClass;

Use to remove top/bottom margins when there are multiple snippets in a row. Use to add a delimiter between code snippets: noGap: true :include-file: file-name.js {title: "part one", noGap: true, collapsed: false} :include-file: simple.c {title: "part two", collapsed: false} class JsClass { constructor() { usefulAction(); } } export default JsClass; #include <iostream> using namespace std; int main() { cout << "hello"; } noGapBorder: true :include-file: ocaml/api.mli {title: "Game", noGap: true, noGapBorder: true} :include-file: ocaml/api.ml module Game : sig type t end module Game = struct type t = { name: string } end

Learn More about highlighting snippets lines.

Read page on Snippets Manipulation to learn more about extracting/modifying snippets before displaying them.