emd

Enhanced Markdown template processor.

See emd README file

TOC

• Install
  • glide
  • Bintray
  • Chocolatey
  • linux rpm/deb repository
  • linux rpm/deb standalone package
• Usage
  • $ emd -help
  • $ emd gen -help
  • $ emd init -help
• Cli examples
• Templates helper
  • Define data
  • Data
  • Functions
  • Files functions
  • Templates functions
  • Go utils functions
  • Markdown functions
  • Cli functions
  • Deprecated function
  • Templates
• API example
  • > main_test.go
• Recipes
  • Generate HTML content
  • Release the project
• History

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. 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. Additionnal data values can be declared using keyValues ...interface{} signature, such as 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. rpkg can be a path to a relative folder like ./emd. It will resolve to 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. maxImportance defines the titles to select by their numbers of #. titles define the title to display, defaults to TOC. 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. Execute and return its response.	emd_exec_pre: "### > ": string to show right before the command line.
shell(s string)	Display a command line header. 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). CsUUID: the codeship project UUID (654654-6465-54...). Within your e.md file use the render function, {{render "badge/codeship" . "CsUUID" "xx" "CsProjectID" "yyy"}}. 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. LicenseFile: The path to the license file. 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

History

CHANGELOG