Awesome
emd
Enhanced Markdown template processor.
See emd README file
TOC
Install
Check the release page!
glide
mkdir -p $GOPATH/src/github.com/mh-cbon/emd
cd $GOPATH/src/github.com/mh-cbon/emd
git clone https://github.com/mh-cbon/emd.git .
glide install
go install
Bintray
choco source add -n=mh-cbon -s="https://api.bintray.com/nuget/mh-cbon/choco"
choco install emd
Chocolatey
choco install emd
linux rpm/deb repository
wget -O - https://raw.githubusercontent.com/mh-cbon/latest/master/bintray.sh \
| GH=mh-cbon/emd sh -xe
# or
curl -L https://raw.githubusercontent.com/mh-cbon/latest/master/bintray.sh \
| GH=mh-cbon/emd sh -xe
linux rpm/deb standalone package
curl -L https://raw.githubusercontent.com/mh-cbon/latest/master/install.sh \
| GH=mh-cbon/emd sh -xe
# or
wget -q -O - --no-check-certificate \
https://raw.githubusercontent.com/mh-cbon/latest/master/install.sh \
| GH=mh-cbon/emd sh -xe
Usage
$ emd -help
emd - 0.0.0
Usage
-h Show help
-help
Show help
-v Show version
-version
Show version
Commands
gen Process an emd file.
init Init a basic emd file.
$ emd gen -help
emd - 0.0.0
Command "gen": Process an emd file.
-data string
JSON map of data
-h Show help
-help
Show help
-in string
Input src file
-out string
Output destination, defaults to stdout (default "-")
$ emd init -help
emd - 0.0.0
Command "init": Init a basic emd file.
-force
Force write
-h Show help
-help
Show help
-out string
Out file (default "README.e.md")
Cli examples
# Init a basic emd file to get started.
emd init
# Reads content of README.e.md, outputs to README.md
emd gen -out README.md
# same with data injections,
emd gen -out README.md --data='{"CsUUID":"xxxx"}'
# use verbose mode
VERBOSE=y emd gen
Templates helper
Define data
Template data can be defined directly into the README.e.md
file using a prelude
,
---
title: "Easygen - Easy to use universal code/text generator"
date: "2016-01-01T22:13:12-05:00"
categories: ["Tech"]
tags: ["go","programming","easygen","CLI"]
---
This prelude
must be inserted right before the regular md
content.
The keys are injected into the template dot
, the value are json
decoded.
Template can access those data using name: {{.categories}} {{.tags}}
Data
Key | Description |
---|---|
ProviderURL | The vcs provider url (example: github.com). |
ProviderName | The vcs provider name (example: github). |
Name | Project name based on the cwd (example: emd). |
User | User name based on the cwd (example: mh-cbon). |
URL | Project url as determined by the cwd (example: github.com/mh-cbon/emd). |
ProjectURL | Project url as determined by the cwd + relative path (example: github.com/mh-cbon/emd/cmd). |
Branch | Current vcs branch name (defaults to master). |
Functions
Functions can be invoked like this {{func "arg1" "arg2"}}
Options are keys to define into the prelude
:
---
emd_cat_pre: "### > "
emd_gotest_pre: "### $ "
emd_exec_pre: "### $ "
emd_shell_pre: "### $ "
---
Files functions
Name | Description | Options |
---|---|---|
cat(f string) | Displays a file header.<br/>Read and return the file body. | emd_cat_pre: "### > " : string to show right before the file path. |
read(f string) | Read and return the file body. | |
yaml(f string, keypaths ...string) | Parse given file as yaml, locate given path into the yaml content, yaml re encode it, return its string. |
Templates functions
Name | Description | Options |
---|---|---|
render(name string, data interface{}, keyValues ...interface{}) | Render given template name, using data .<br/> Additionnal data values can be declared using keyValues ...interface{} signature, such as <br/>render("x", data, "key1", "val1", "key2", "val2") . | |
set(name string, x interface{}) | Save given value x as name on dot . . |
Go utils functions
Name | Description | Options |
---|---|---|
pkgdoc(files ...string) | Read the first of files , or main.go , lookup for its package comment and return it as plain text. | |
gotest(rpkg string, run string, args ...string) | Run go test <rpkg> -v -run <run> <args> , return its output. <br/>rpkg can be a path to a relative folder like ./emd . It will resolve to <br/>github.com/mh-cbon/emd/emd | emd_gotest_pre: "### $ " defines a sring to show right before the go test command line. |
Markdown functions
Name | Description | Options |
---|---|---|
color(color string, content string]) string | Embed given content with triple backquote syntax colorizer support. | |
toc(maxImportance int, title ...string) string | Displays a TOC of the README file being processed.<br/>maxImportance defines the titles to select by their numbers of # .<br/>titles define the title to display, defaults to TOC .<br/>Titles displayed before the call to {{toc x}} are automatically ignored. | |
preline(pre string, content string) string | Prepend every line of content with pre . | |
echo(f string) string | Prints f , usefull to print strings which contains the template tokens. | |
link(url string, text ...string) string | Prints markdown link. | |
img(url string, alt ...string) string | Prints markdown image. | |
concat(x ...string) string | Concat all x . | |
pathjoin(x ...string) string | Join all x with / . |
Cli functions
Name | Description | Options |
---|---|---|
exec(bin string, args ...string) | Display a command line header.<br/>Execute and return its response. | emd_exec_pre: "### > " : string to show right before the command line. |
shell(s string) | Display a command line header.<br/>Execute the command on a shell, and return the its response. | emd_shell_pre: "### > " : string to show right before the command line. |
Deprecated function
Name | Description |
---|---|
file(f string[, colorizer string]) | Read and display a file enclosed with triples backquotes. If colorizer is empty, it defaults to the file extension. |
cli(bin string, args ...string) | Execute and display a command line enclosed with triples backquotes. The highlight defaults to sh . |
Templates
std
Name | Description | Params |
---|---|---|
gh/releases | Show a text to link the release page. | |
badge/travis | Show a travis badge. | |
badge/appveyor | Show an appveyor badge. | |
badge/codeship | Show a codeship badge. | CsProjectID: The codeship project ID (123465).<br/> CsUUID: the codeship project UUID (654654-6465-54...).<br/>Within your e.md file use the render function, {{render "badge/codeship" . "CsUUID" "xx" "CsProjectID" "yyy"}} .<br/>Via cli, add it with --data '{"CsUUID": "xx", "CsProjectID":"yy"}' . |
choco_bintray/install | Show a snippet to install the package with chocolatey from bintray repos. | BintrayRepo: the name of the bintray repo (default: choco ) |
choco/install | Show a snippet to install the package with chocolatey. | |
linux/gh_src_repo | Show an sh snippet to install the package via `rpm | deb |
linux/bintray_repo | Show an sh snippet to install the package via `rpm | deb |
linux/gh_pkg | Show an sh snippet to install the package via standalone packages (deb/rpm). | |
license/shields | Show a license badge. | License: The license name like MIT , BSD .<br/>LicenseFile: The path to the license file.<br/>LicenseColor: The color of the badge (defaults t o blue). |
go
Name | Description | Params |
---|---|---|
go/install | Show an sh snippet to install the package via go get . | |
badge/godoc | Show a godoc badge. | |
badge/goreport | Show a goreport badge. |
go-nonstd
Name | Description | Params |
---|---|---|
glide/install | Show an sh snippet to install the package via glide . |
API example
> main_test.go
package main_test
import (
"os"
"github.com/mh-cbon/emd/emd"
"github.com/mh-cbon/emd/std"
)
var projectName = "dummy"
// ExampleGenerate demonstrates the generation
// of the given README.e.md source file
// to os.Stdout.
func Example() {
// make a new instance of emd.Generator.
gen := emd.NewGenerator()
// set the main template.
gen.AddTemplate("{{.Name}}")
// set the data available in templates.
gen.SetDataMap(map[string]interface{}{"Name": projectName})
// register a plugin
if err := std.Register(gen); err != nil {
panic(err)
}
// process the template.
if err := gen.Execute(os.Stdout); err != nil {
panic(err)
}
// Output: dummy
}
Recipes
Generate HTML content
To directly generate HTML content out of emd
output, for example, with gh-markdown-cli
,
npm install gh-markdown-cli -g
emd gen | mdown
Release the project
gump patch -d # check
gump patch # bump