blackfridaytext

README

Blackfriday Text

A text renderer for the Blackfriday Markdown Processor.

This can be useful for quick displays of Markdown files, of course, but one use I've found for it is nicer CLI output. For an example, see the output of the ring command from http://github.com/gholt/ring

API Documentation

Copyright Gregory Holt. All rights reserved.
Use of this source code is governed by a BSD-style
license that can be found in the LICENSE file.

Example Code

package main

import (
    "io/ioutil"
    "os"

    "github.com/gholt/blackfridaytext"
)

func main() {
    opt := &blackfridaytext.Options{Color: true}
    if len(os.Args) == 2 && os.Args[1] == "--no-color" {
        opt.Color = false
    }
    markdown, _ := ioutil.ReadAll(os.Stdin)
    metadata, output := blackfridaytext.MarkdownToText(markdown, opt)
    for _, item := range metadata {
        name, value := item[0], item[1]
        os.Stdout.WriteString(name)
        os.Stdout.WriteString(":\n    ")
        os.Stdout.WriteString(value)
        os.Stdout.WriteString("\n")
    }
    os.Stdout.WriteString("\n")
    os.Stdout.Write(output)
    os.Stdout.WriteString("\n")
}

---

Sample Input

To give an idea of what the output looks like, I've run this document through the renderer and appended the output.

• Here is a sample list.
• Two
  • And a sublist.
  • Two, part B.
• Three

Emphasis, Double Emphasis, Triple Emphasis, Strikethrough, and code spans along with http://auto/linking and explicit linking.

Here's a quick table from the blackfriday example:

Name	Age
Bob	27
Alice	23

---

No-Color Output

--[ Blackfriday Text ]--

    --[ A text renderer for the [Blackfriday Markdown Processor]
        http://github.com/russross/blackfriday. ]--

        This can be useful for quick displays of Markdown files, of course,
        but one use I've found for it is nicer CLI output. For an example, see
        the output of the "ring" command from http://github.com/gholt/ring

        [API Documentation] http://godoc.org/github.com/gholt/blackfridaytext

        > Copyright Gregory Holt. All rights reserved.
        > Use of this source code is governed by a BSD-style
        > license that can be found in the LICENSE file.

    --[ Example Code ]--

        package main

        import (
            "io/ioutil"
            "os"

            "github.com/gholt/blackfridaytext"
        )

        func main() {
            opt := &blackfridaytext.Options{Color: true}
            if len(os.Args) == 2 && os.Args[1] == "--no-color" {
                opt.Color = false
            }
            markdown, _ := ioutil.ReadAll(os.Stdin)
            metadata, output := blackfridaytext.MarkdownToText(markdown, opt)
            for _, item := range metadata {
                name, value := item[0], item[1]
                os.Stdout.WriteString(name)
                os.Stdout.WriteString(":\n    ")
                os.Stdout.WriteString(value)
                os.Stdout.WriteString("\n")
            }
            os.Stdout.WriteString("\n")
            os.Stdout.Write(output)
            os.Stdout.WriteString("\n")
        }

        -----------------------------------------------------------------------

    --[ Sample Input ]--

        To give an idea of what the output looks like, I've run this document
        through the renderer and appended the output.
          * Here is a sample list.
          * Two
              * And a sublist.
              * Two, part B.
          * Three

        *Emphasis*, **Double Emphasis**, ***Triple Emphasis***,
        ~~Strikethrough~~, and "code spans" along with http://auto/linking and
        [explicit linking] http://explicit/linking.

        Here's a quick table from the blackfriday example:

        +-------+-----+
        | Name  | Age |
        +-------+-----+
        | Bob   | 27  |
        | Alice | 23  |
        +-------+-----+

---

Color Output

Documentation

Overview

Package blackfridaytext contains a text renderer for the Blackfriday Markdown Processor http://github.com/russross/blackfriday.

The Markdown supported is that supported by BlackFriday itself, with its tables, fenced code, autolinking, strikethrough, and definition lists turned on.

There is optional support for colorized output, as well as line wrapping and reflowing elements such as tables.

There is also optional support for Markdown Metadata https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-Syntax-Guide#metadata and summary information.

Index

• func MarkdownMetadata(markdown []byte) ([][]string, int)
• func MarkdownToText(markdown []byte, opt *Options) ([][]string, []byte)
• func MarkdownToTextNoMetadata(markdown []byte, opts *Options) []byte
• type Options

Functions

func MarkdownMetadata

func MarkdownMetadata(markdown []byte) ([][]string, int)

MarkdownMetadata parses just the metadata from the markdown and returns the metadata and the position of the rest of the markdown.

The metadata is a [][]string where each []string will have two elements, the metadata item name and the value. Metadata is an extension of standard Markdown and is documented at https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-Syntax-Guide#metadata -- this implementation currently differs in that it does not support multiline values.

In addition, the rest of markdown is scanned for lines containing only "///".

If there is one "///" line, the text above that mark is considered the "Summary" metadata item; the summary will also be treated as part of the content (with the "///" line omitted). This is known as a "soft break".

If there are two "///" lines, one right after the other, the summary will only be contained in the "Summary" metadata item and not part of the main content. This is known as a "hard break".

func MarkdownToText

func MarkdownToText(markdown []byte, opt *Options) ([][]string, []byte)

MarkdownToText parses the markdown using the Blackfriday Markdown Processor and an internal renderer to return any metadata and the formatted text. If opt is nil the defaults will be used.

See MarkdownMetadata for a description of the [][]string metadata returned.

func MarkdownToTextNoMetadata

func MarkdownToTextNoMetadata(markdown []byte, opts *Options) []byte

MarkdownToTextNoMetadata is the same as MarkdownToText only skipping the detection and parsing of any leading metadata. If opts is nil the defaults will be used.

Types

type Options

type Options struct {
	// Width indicates how long to attempt to restrict lines to and may be a
	// positive int for a specific width, 0 for the default width (attempted to
	// get from terminal, 79 otherwise), or a negative number for a width
	// relative to the default.
	Width int
	// Color set true will allow ANSI Color Escape Codes.
	Color bool
	// The following are the byte values for each color output for the
	// differing elements. Each will be followed by ColorReset. Usually these
	// are set to whatever ANSI escape sequences you want. Left nil, they will
	// be set to reasonable defaults. See brimtext.ANSIEscape for some quick
	// examples to use.
	ColorHeader         []byte
	ColorLink           []byte
	ColorImage          []byte
	ColorCodeSpan       []byte
	ColorBlockCode      []byte
	ColorStrikethrough  []byte
	ColorEmphasis       []byte
	ColorDoubleEmphasis []byte
	ColorTripleEmphasis []byte
	ColorReset          []byte
	// Indent1 is the prefix for the first line.
	Indent1 []byte
	// Indent2 is the prefix for any second or subsequent lines.
	Indent2           []byte
	TableAlignOptions *brimtext.AlignOptions
	// HeaderPrefix is the prefix before any header line.
	HeaderPrefix []byte
	// HeaderSuffix is the suffix after any header line.
	HeaderSuffix []byte
}

Options contains the configuration for MarkdownToText and MarkdownToTextNoMetadata.