@sytone/markdown-snippet-injector

Welcome to markdown-snippet-injector

A tool for injecting code snippets into Markdown files:

1. Define snippets in your source by using a simple notation
2. Put placeholders associated with the snippets in your MarkDown files
3. Run MarkDown injector to replace the placeholders during your documentation build:

mdinject --root=<path-to-source-code> --docs-root=<path-to-docs>

Options

      --help                          Show help                        [boolean]
      --version                       Show version number              [boolean]
  -r, --root                          Root of snippet sources
                       [string] [default: current working directory plus "/src"]
  -d, --docs-root                     Root of documentation sources
                      [string] [default: current working directory plus "/docs"]
      --snippet-titles                Suffix used for the placeholder command in
                                      the target files.
                                              [default: "JavaScript|TypeScript"]
  -l, --log-level                     Level of detail in logs
     [choices: "none", "error", "warning", "info", "verbose", "debug"] [default:
                                                                         "info"]
      --wrap                          Wrap the snippet around the snippet
                                      content if possible.
                                                       [boolean] [default: true]
  -s, --source-file-extension-filter  File extension filter for source files
                                                            [default: ".js|.ts"]
  -t, --target-file-extension-filter  File extension filter for source files
                                                                [default: ".md"]
      --placeholder-prefix            Prefix used for the placeholder command in
                                      the target files.          [default: "%%"]
      --placeholder-suffix            Suffix used for the placeholder command in
                                      the target files.          [default: "%%"]

Using markdown-snippet-injector

Defining snippets in JavaScript and TypeScript source files

Defining code snippets in your source files is done by enclosing them with a starting token and ending token prefixed by a line comment.

After the comment the two character >> indicate that there is a starting token. Next come the id of the snippet, this is wrapped in single quotes like this id='snippet-name-goes-here' next are options, if you are not setting any it should be empty like this options=''

Full example without an option:

  // >> id='snippetinjector-hasSnippet' options=''

Full example with an option:

  // >> id='snippetinjector-hasSnippet' options='file=snippetinjector/hassnippet.md'

The enmding token is simpler, it is the comment followed by two characters << indicating end and then the name of the snippet. the id key is not needed for the end.

Full example without an option:

  // << snippetinjector-hasSnippet

Examples of what it would looks like in code files.

// >> id='sum-snippet' options=''
export function sum(a, b){
    return a + b;
}
// << sum-snippet

// >> id='multiplication-snippet' options=''
export function multiply(a, b){
    return a * b;
}
// << multiplication-snippet

// >> id='division-snippet' options='file=math/divide.md'
export function divide(a, b){
    return a / b;
}
// << division-snippet

Defining source snippets in XML files

For XML files the same process is followed with the <!-- and --> comment tokens wrapping the starting and ending tags.

<!-- >> id='list-plants' options='file=math/divide.md' -->
<Plants>
  <Plant id="adj435">
    <Name>Rose</Name>
  </Plant>
  <Plant id="j239fj">
    <Name>Daisy</Name>
  </Plant>
</Plants>
<!-- << list-plants -->

Defining source snippets in CSS files

For CSS files the same process is followed with the /* and */ comment tokens wrapping the starting and ending tags.

Code snippets inside CSS files are defined as follows:

/* >> id='css-snippet' options='file=math/divide.md' */
.btn {
    color: green;
    text-align: center;
}
/* << css-snippet */

Source Snippet Options

You can specify multiple options, use th & character to separate them.

Destination File

file=<path and filename>

You can specify a file in options and when the source files are processed it will create the file and insert the contents. This allows you to make multiple files without having to keep on adding the markdown files with the placeholders in them.

Header File and Footer File

header=<path and filename>

footer=<path and filename>

If specified with the file option it will use the contents of these files to insert before and after the snippet.

Defining placeholders for the snippets in your MarkDown files

Use the %%snippet id='<your-snippet-id>' options=''/%% notation to define the corresponding placeholders in your markdown files. They will be replaced by the snippet injector when run. The starting and ending characters can be specified via command line options.

    # Using the multiply function:
        %%snippet id='multiplication-snippet'/%%
    # Using the sum function:
        %%snippet id='sum-snippet'/%%

If you set --wrap flag your snippets will be wrapped around the snippet notation you have been provided. This way when you update your snippet source - the markdown-snippet-injector will reflect the changes in your markdown as well.

Example:

mdinject --wrap --root=<path-to-source-code> --docs-root=<path-to-docs>

main.css

/* >> id='css-snippet; options='' */
.btn {
    color: green;
    text-align: center;
}
/* << css-snippet */

README.MD

This is a CSS snippet
%%snippet id='css-snippet'/%%

After first build the README.MD will looks like:

This is a CSS snippet
%%snippet id='css-snippet'%%
```

.btn {
    color: green;
    text-align: center;
}

```
%%/snippet%%

Then when you update main.css, your README.MD will be updated as well.

Advanced features

Nested snippets

Nested snippets are also supported. This is helpful in scenarios where you want to explain parts of a larger snippet in steps:

// >> view-model-snippet
export class ViewModel {

    private _items: ObservableArray<DataItem>;

    constructor() {
        this.initDataItems();
    }

    get dataItems() {
        return this._items;
    }
// >> handling-event-snippet
    public onShouldRefreshOnPull(args: listViewModule.ListViewEventData) {
        var that = new WeakRef(this);
        console.log("Event fired");
        timer.setTimeout(function() {
            for (var i = 0; i < 25; i++) {
                that.get()._items.splice(0, 0, new DataItem(that.get()._items.length, "Item " + that.get()._items.length, "This is item description."));

            }
            var listView = args.object;
            listView.notifyPullToRefreshFinished();
        }, 1000);

    }    
// << handling-event-snippet

    private initDataItems() {
        this._items = new ObservableArray<DataItem>();

        for (var i = 0; i < 25; i++) {
            this._items.push(new DataItem(i, "Item " + i, "This is item description."));
        }
    }
}

export class DataItem {
    public id: number;
    public itemName;
    public itemDescription;

    constructor(id: number, name: string, description: string) {
        this.id = id;
        this.itemName = name;
        this.itemDescription = description;
    }
}
// << view-model-snippet

This will produce two code snippets: one containing the whole view-model class and the other containing the onShouldRefreshOnPull function.

Hiding Blocks

You can mark parts of the original code to be hidden - not shown in the documentation:

// >> ts-snippet-with-hidden-section
export function div(a, b){
    // >> (hide)
    console.log("You should not see this!")
    // << (hide)    
    return a / b;
}
// << ts-snippet-with-hidden-section

The syntax is similar in XML and CSS.

Defining file extension filters

You can choose what kind of files will be processed during snippet injection by using the -s, --source-file-extension-filter and -t, --target-file-extension-filter parameters. The default values of these properties are .ts and .md respectively.

Multiple source and target extension types

You can define multiple source or target extension types by setting the corresponding parameters to a set of extensions separated by a |:

mdinject --root=. --docs-root=../ --source-file-extension-filter=".ts|.js" --target-file-extension-filter=".md|.txt"

In this way all target files will be processed and the corresponding snippet placeholders will be replaced.

Defining a title for the injected snippet

When injected, a snippet is formatted using the default MarkDown code-snippet format. You can append a title to the injected snippet by using the --snippettitles parameter. By default, .js and .ts files are recognized and the snippets coming from them are titled JavaScript or TypeScript. You can define custom snippet titles by setting the --snippettitles parameter to a set of titles separated by a |:

mdinject --root=. --docs-root=../ --source-file-extension-filter=".java|.cs" --target-file-extension-filter=".md|.txt" --snippet-titles="Java|C#"

Note that the order of the snippet titles must be the related to the order of the source extension types so that they match.

Run e2e tests

1. Clone repo
2. npm install
3. npm test

E2E tests are developed with Mocha.

Release Process

Update version in package.json

npm run build npm publish