Home

Awesome

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: {{.categories}} {{.tags}}

Data

KeyDescription
ProviderURLThe vcs provider url (example: github.com).
ProviderNameThe vcs provider name (example: github).
NameProject name based on the cwd (example: emd).
UserUser name based on the cwd (example: mh-cbon).
URLProject url as determined by the cwd (example: github.com/mh-cbon/emd).
ProjectURLProject url as determined by the cwd + relative path (example: github.com/mh-cbon/emd/cmd).
BranchCurrent 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

NameDescriptionOptions
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

NameDescriptionOptions
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

NameDescriptionOptions
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/emdemd_gotest_pre: "### $ " defines a sring to show right before the go test command line.

Markdown functions

NameDescriptionOptions
color(color string, content string]) stringEmbed given content with triple backquote syntax colorizer support.
toc(maxImportance int, title ...string) stringDisplays 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) stringPrepend every line of content with pre.
echo(f string) stringPrints f, usefull to print strings which contains the template tokens.
link(url string, text ...string) stringPrints markdown link.
img(url string, alt ...string) stringPrints markdown image.
concat(x ...string) stringConcat all x.
pathjoin(x ...string) stringJoin all x with /.

Cli functions

NameDescriptionOptions
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

NameDescription
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
NameDescriptionParams
gh/releasesShow a text to link the release page.
badge/travisShow a travis badge.
badge/appveyorShow an appveyor badge.
badge/codeshipShow 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/installShow a snippet to install the package with chocolatey from bintray repos.BintrayRepo: the name of the bintray repo (default: choco)
choco/installShow a snippet to install the package with chocolatey.
linux/gh_src_repoShow an sh snippet to install the package via `rpmdeb
linux/bintray_repoShow an sh snippet to install the package via `rpmdeb
linux/gh_pkgShow an sh snippet to install the package via standalone packages (deb/rpm).
license/shieldsShow 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
NameDescriptionParams
go/installShow an sh snippet to install the package via go get.
badge/godocShow a godoc badge.
badge/goreportShow a goreport badge.
go-nonstd
NameDescriptionParams
glide/installShow 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