https://github.com/nativescript/markdown-snippet-injector
A tool for injecting code snippets into MarkDown files.
https://github.com/nativescript/markdown-snippet-injector
Last synced: 8 months ago
JSON representation
A tool for injecting code snippets into MarkDown files.
- Host: GitHub
- URL: https://github.com/nativescript/markdown-snippet-injector
- Owner: NativeScript
- License: mit
- Created: 2016-02-18T12:19:08.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2019-03-14T05:31:00.000Z (about 7 years ago)
- Last Synced: 2024-10-29T15:51:51.418Z (over 1 year ago)
- Language: TypeScript
- Size: 49.8 KB
- Stars: 4
- Watchers: 30
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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= --docsroot=`
# Using `markdown-snippet-injector`
## Defining snippets in `JavaScript` and `TypeScript` source files
Defining code snippets in your source files is done by enclosing them as shown below:
```
// >> sum-snippet
export function sum(a, b){
return a + b;
}
// << sum-snippet
// >> multiplication-snippet
export function multiply(a, b){
return a * b;
}
// << multiplication-snippet
// >> division-snippet
export function divide(a, b){
return a / b;
}
// << division-snippet
```
## Defining source snippets in `XML` files
If you want to define a code-snippet in a `XML` file you should use the following approach:
```XML
```
## Defining source snippets in `CSS` files
Code snippets inside CSS files are defined as follows:
``` CSS
/* >> css-snippet */
.btn {
color: green;
text-align: center;
}
/* << css-snippet */
```
## Defining placeholders for the snippets in your `MarkDown` files
Use the `` notation to define the corresponding placeholders in your markdown files. They will be replaced by the snippet injector when run:
```MarkDown
# Using the multiply function:
# Using the sum function:
```
If you set `-w` flag your snippets will be wrapped around the snippet notation you have been provided. This way when you update your snipet source - the `markdown-snippet-injector` will reflect the changes in your markdown as well.
Example:
`mdinject -w --root= --docsroot=`
main.css
```
/* >> css-snippet */
.btn {
color: green;
text-align: center;
}
/* << css-snippet */
```
README.MD
```
This is a CSS snippet
```
After first build the README.MD will looks like:
```
This is a CSS snippet
```
.btn {
color: green;
text-align: center;
}
```
```
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;
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();
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
// >> 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 `--sourceext` and `--targetext` 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=. --docsroot=../ --sourceext=".ts|.js" --targetext=".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=. --docsroot=../ --sourceext=".java|.cs" --targetext=".md|.txt" --snippettitles="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](https://mochajs.org).