Embedding Content

To reduce documentation maintenance burden avoid copy and paste of code snippets. Embed content by referencing existing files using the :include-file: plugin instead. :include-file: file-name.js This include- syntax will appear throughout the documentation and represents a family of custom Markdown extensions. class JsClass { constructor() { usefulAction() } } export default JsClass 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 lookup-paths file

Syntax highlighting

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

Title

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

Wide Code

Use the wide option to stretch wide code to occupy as much horizontal screen real estate as possible. :include-file: WideCode.java {wide: true} class InternationalPriceService implements PriceService { private static void LongJavaInterfaceNameWithSuperFactory createMegaAbstractFactory(final ExchangeCalendarLongerThanLife calendar) { ... } } Without the wide option code will be aligned with the rest of the text and users can use scrollbars. class InternationalPriceService implements PriceService { private static void LongJavaInterfaceNameWithSuperFactory createMegaAbstractFactory(final ExchangeCalendarLongerThanLife calendar) { ... } } 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.

Read More

If you have a file with large code snippet and you want to initially display only a small fraction use readMore option with an optional readMoreVisibleLines option to specify a number of initial lines displayed (default is 8). :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"); } }

Highlights

Use the highlight option to bring readers attention to the important lines. :include-file: file-name.js {highlight: "export"} class JsClass { constructor() { usefulAction() } } export default JsClass It is recommended to pass a substring, but you can pass a line idx (starts from 0). Additionally you can combine two approaches and pass a list of things to highlight. :include-file: file-name.js {highlight: ["export", 1]} class JsClass { constructor() { usefulAction() } } export default JsClass Note: Order of lines to highlight is reflected during presentation modeUse the highlightPath option to highlight lines specified in a separate file. :include-file: file-name.js {highlightPath: "lines-to-highlight.txt"} class JsClass { constructor() { usefulAction() } } export default JsClass class usefulAction

Limit

Use startLine , endLine to limit the included content.If you have a file with embedded examples, you can use limit function to extract small samples by using marker lines. import market def main(): # example: book trade id = market.book_trade('symbol', market.CURRENT_PRICE, 100) # example-end # example: cancel trade market.cancel_trade('id') # example-end if __name__ == "__main__": main() :include-file: python-examples.py {startLine: "example: book trade", endLine: "example-end"} # example: book trade id = market.book_trade('symbol', market.CURRENT_PRICE, 100) # example-end Note: Lines match doesn't have to be exact, contains is used.By default startLine and endLine are included in the rendered result. Use excludeStartEnd: true to remove markers. :include-file: python-examples.py { startLine: "example: book trade", endLine: "example-end", excludeStartEnd: true } id = market.book_trade('symbol', market.CURRENT_PRICE, 100) Use includeRegexp to include only lines matching regexp(s). :include-file: python-examples.py {includeRegexp: "import"} :include-file: python-examples.py {includeRegexp: ["import"]} import market Use excludeRegexp to exclude lines matching regexp(s). :include-file: python-examples.py {excludeRegexp: "# example"} :include-file: python-examples.py {excludeRegexp: ["# example"]} import market def main(): id = market.book_trade('symbol', market.CURRENT_PRICE, 100) market.cancel_trade('id') if __name__ == "__main__": main()

Callout Comments

If you already have comments inside your code it would be non efficient to repeat them inside documentation. Instead, comments can be automatically extracted and presented as part of the textGiven file with inlined comments class JsClass { constructor() { // new syntax for constructor } } export default JsClass // new syntax for ES6 modules By specifying commentsType :include-file: file-name-with-comments.js {commentsType: "inline"} It will be rendered as class JsClass { constructor() { // new syntax for constructor } } export default JsClass // new syntax for ES6 modules Comment lines can be put above a code line. All the comment lines will be merged and applied to the next code line. order = fetch_order() # explanation of why # strategic price calculation # is important here price = strategic_price_calc(order) order = fetch_order() # explanation of why # strategic price calculation # is important here price = strategic_price_calc(order)

Spoilers

Set the spoiler property to initially hide explanations. It may be useful when teaching. :include-file: file-name-with-comments.js {commentsType: "inline", spoiler: true} Click on the spoiler to reveal the explanations: class JsClass { constructor() { // new syntax for constructor } } export default JsClass // new syntax for ES6 modules