emd

travis Status Appveyor Status Go Report Card GoDoc MIT License

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: ` `

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 ``

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 `` 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, ``.
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|apt repositories hosted on gh-pages.  
linux/bintray_repo Show an sh snippet to install the package via rpm|deb|apt repositories hosted on bintray.  
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("")

	// 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