embedmd

Documentation

Overview

Package embedmd provides a single function, Process, that parses markdown searching for markdown comments.

The format of an embedmd command is:

[embedmd]:# (pathOrURL language /start regexp/ /end regexp/)

The embedded code will be extracted from the file at pathOrURL, which can either be a relative path to a file in the local file system (using always forward slashes as directory separator) or a url starting with http:// or https://. If the pathOrURL is a url the tool will fetch the content in that url. The embedded content starts at the first line that matches /start regexp/ and finishes at the first line matching /end regexp/.

Omitting the the second regular expression will embed only the piece of text that matches /regexp/:

[embedmd]:# (pathOrURL language /regexp/)

To embed the whole line matching a regular expression you can use:

[embedmd]:# (pathOrURL language /.*regexp.*\n/)

If you want to embed from a point to the end you should use:

[embedmd]:# (pathOrURL language /start regexp/ $)

Finally you can embed a whole file by omitting both regular expressions:

[embedmd]:# (pathOrURL language)

You can ommit the language in any of the previous commands, and the extension of the file will be used for the snippet syntax highlighting. Note that while this works Go files, since the file extension .go matches the name of the language go, this will fail with other files like .md whose language name is markdown.

[embedmd]:# (file.ext)

Index

• func Process(ctx context.Context, out io.Writer, in io.Reader, opts ...Option) error
• type Fetcher
• type Option
  • func WithBaseDir(path string) Option
  • func WithFetcher(c Fetcher) Option

Functions

func Process

func Process(ctx context.Context, out io.Writer, in io.Reader, opts ...Option) error

Process reads markdown from the given io.Reader searching for an embedmd command. When a command is found, it is executed and the output is written into the given io.Writer with the rest of standard markdown.

Types

type Fetcher

type Fetcher interface {
	Fetch(dir, path string) ([]byte, error)
}

Fetcher provides an abstraction on a file system. The Fetch function is called anytime some content needs to be fetched. For now this includes files and URLs. The first parameter is the base directory that could be used to resolve relative paths. This base directory will be ignored for absolute paths, such as URLs.

type Option

type Option struct {
	// contains filtered or unexported fields
}

An Option provides a way to adapt the Process function to your needs.

func WithBaseDir

func WithBaseDir(path string) Option

WithBaseDir indicates that the given path should be used to resolve relative paths.

func WithFetcher

func WithFetcher(c Fetcher) Option

WithFetcher provides a custom Fetcher to be used whenever a path or url needs to be fetched.