Syntax Highlighting

SSG is a Static Site Generator. It uses Go's templates, so you need to be familiar and comfortable with text/templates from Go's stdlib. It can cope with input files of any type, parsing and running them as templates. If the input file happens to be markdown (i.e. has a .md extension) then ssg will run the input file as a template, and then attempt to convert the result from markdown to HTML. It uses https://github.com/gomarkdown/markdown to do this (and https://github.com/alecthomas/chroma for syntax highlighting of code blocks). Pages can, in their meta data, specify an "outer" template name. If given, the result of running the page as a template (and converting from markdown to HTML if necessary) is then passed to the named outer template. This means you can use a common outer template to add headers, footers, structure etc to pages. It is trivial to create your own templates and template snippets: just make sure you set `output = false` in the meta data of such files, and there will be no attempt made to convert such files to output; instead they will solely be made available for use by other templates.

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package syntaxhighlight provides syntax highlighting for code. It currently uses a language-independent lexer and performs decently on JavaScript, Java, Ruby, Python, Go, and C.

Package strinterp provides a demonstration of morally correct string interpolation. This package was created in support of a blog post about why we are still writing insecure software in 2015: http://www.jerf.org/iri/post/2942 It's the result of about 20 hours of screwing around. I meant to keep it shorter, but I started to have too much fun. "Morally" correct means that I intend this to demonstrate a point about API and language design, and that any actual utility is a bit coincidental. That said, as this developed it became potentially more useful than I had initially intended, because instead of expressing all the interpolations in terms of strings, they are all expressed in terms of io.Writers. Since this library also permits inputting the strings to be interpolated in the form of io.Readers, this means that this entire library is fully capable of string interpolation in the middle of streams, not just strings. Or, if you prefer, this is a *stream* interpolator. The "str" in "strinterp" is pleasingly ambiguous. This documentation focuses on usage; for the reasoning behind the design, consult the blog post. To use this package, create an interpolator object: You can then use it to interpolate strings. The simplest case is concatenation: See the blog post for a discussion of why this is deliberately a bit heavyweight and *designed* to call attention to the use of "RAW", rather than making such usage a simple and quiet default behavior. The "format string", the first element of the call, has the following syntax: You may backslash-escape any of the pipe, colon, or semicolon to pass them through as arguments to the formatter/encoder, or backslash itself to pass it through. (The formatter/encoder will of course receive the decoded bytes without the escaping backslash.) To emit a raw %, use "%%;". Here is an example of a format string that uses all these features: This will result in the standard encoding/json encoding being used on the obj, then it will be converted to base64, which will use the encoding/base64 URLEncoding due to the "url" argument being passed. You can continue piping to further encoders indefinitely. There are two different kinds of interpolators you can write, formatters and encoders. A "formatter" is a routine that takes a Go value of some sort and converts it to some bytes to be written out via a provided io.Writer. A formatter has the function signature defined by the Formatter type, which is: When called, the function should first examine the parameters. If it doesn't like the parameters, it should return ErrUnknownArguments, properly filled out. (Note: It is important to be strict on the parameters; if they don't make perfect sense, this is your only chance to warn a user about that.) It should then take the arg and write it out to the io.Writer in whatever manner makes sense, then return either the error obtained during writing or nil if it was fully successful. You want to write a Formatter when you are trying to convert something that isn't already a string, []byte, or io.Reader into output. Therefore it only makes sense in the first element of a formatter's pipeline (the "json" in the previous example), because only a formatter can handle arbitrary objects. See the Formatter documentation below for more gritty details. An "encoder" is a routine that receives incoming io.Writer requests, modifies them in a suitable manner, and passes them down to the next io.Writer in the chain. In other words it takes []byte and generates further []byte from them. You want to write an Encoder when either you want to transform input going through it (like escaping), or when you know the only valid input coming in will be in the form of a string, []byte, or io.Reader, which strinterp will automatically handle feeding down the encoder pipeline. See the Encoder documentation below for more gritty details. To configure your interpolator, you will need to add additional formatters and encoders to the interpolator so it is aware of them. NewInterpolator will return a bare *Interpolator with only the "RAW" encoder. A DefaultInterpolator is also provided that comes preconfigured for some HTML- and JSON-type-tasks. Consulting the "examples.go" file in the godoc file listing below will highlight these formatters and interpolators for your cribbing convenience. Use the AddFormatter and AddEncoder functions to add these to your interpolator to configure it. (Since I find people often get a sort of mental block around this, remember that, for instance, even though I provide you a default JSON streamer based on the standard encoding/json library, if you have something else you prefer, you can always specify a *different* json formatter for your own usage.) Once configured, for maximum utility I recommend putting string interpolation into your environment object. See http://www.jerf.org/iri/post/2929 . It is also possible to directly use the Encoders, as their type signature tends to imply (note how you don't have to pass them any *Interpolator or any other context). Ideally you instantiate a WriterStack around your target io.Writer and .Push encoders on top of that, as WriterStack handles some corner cases around Encoders that want to be "Close"d, then call .Finish() on the WriterStack when done, which DOES NOT close the underlying io.Writer. This is probably the maximally-performing way to do this sort of encoding in a stream. This is true of all string interpolators, but even more so of strinterp since it can be hooked up to arbitrary formatters and encoders. You MUST NOT feed user input as the interpolation source string. In fact I'd suggest that one could make a good case that the first parameter to strinterp should always be a constant string in the source code base, and if I were going to write a local validation routine to plug into go vet or something I'd probably add that as a rule. Again, let me emphasize, this is NOT special to strinterp. You shouldn't let users feed into the first parameter of fmt.Sprintf, or any other such string, in any language for that matter. It's possible some are "safe" to do that in, but given the wide range of havoc done over the years by letting users control interpolation strings, I would just recommend against it unconditionally. Even when "safe" it probably isn't what you mean. Care should also be taken in the construction of filters. If they get much "smarter" than a for loop iterating over bytes/runes and doing "something" with them, you're starting to ask for trouble if user input passes through them. Generally the entire point of strinterp is to handle potentially untrusted input in a safe manner, so if you start "interpreting" user input you could be creating openings for attackers. I'm interested in pull requests for more Formatters and Encoders for the "default Interpolator", though ideally only for things in the standard library.

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package bfchroma provides an easy and extensible blackfriday renderer that uses the chroma syntax highlighter to render code blocks.

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package bfchroma provides an easy and extensible blackfriday renderer that uses the chroma syntax highlighter to render code blocks.

The present file format Present files have the following format. The first non-blank non-comment line is the title, so the header looks like The subtitle, date, and tags lines are optional. The date line may be written without a time: In this case, the time will be interpreted as 10am UTC on that date. The tags line is a comma-separated list of tags that may be used to categorize the document. The author section may contain a mixture of text, twitter names, and links. For slide presentations, only the plain text lines will be displayed on the first slide. Multiple presenters may be specified, separated by a blank line. After that come slides/sections, each after a blank line: Title of slide or section (must have asterisk) Some Text ** Subsection bullets more bullets a bullet with *** Sub-subsection Some More text Preformatted text is indented (however you like) Further Text, including invocations like: .code x.go /^func main/,/^}/ .play y.go .image image.jpg .background image.jpg .iframe http://foo .link http://foo label .html file.html .caption _Gopher_ by [[https://www.instagram.com/reneefrench/][Renée French]] Again, more text Blank lines are OK (not mandatory) after the title and after the text. Text, bullets, and .code etc. are all optional; title is not. Lines starting with # in column 1 are commentary. Fonts: Within the input for plain text or lists, text bracketed by font markers will be presented in italic, bold, or program font. Marker characters are _ (italic), * (bold) and ` (program font). An opening marker must be preceded by a space or punctuation character or else be at start of a line; similarly, a closing marker must be followed by a space or punctuation character or else be at the end of a line. Unmatched markers appear as plain text. There must be no spaces between markers. Within marked text, a single marker character becomes a space and a doubled single marker quotes the marker character. Inline links: Links can be included in any text with the form [url[label]], or [url] to use the URL itself as the label. Functions: A number of template functions are available through invocations in the input text. Each such invocation contains a period as the first character on the line, followed immediately by the name of the function, followed by any arguments. A typical invocation might be (except that the ".play" must be at the beginning of the line and not be indented like this.) Here follows a description of the functions: code: Injects program source into the output by extracting code from files and injecting them as HTML-escaped <pre> blocks. The argument is a file name followed by an optional address that specifies what section of the file to display. The address syntax is similar in its simplest form to that of ed, but comes from sam and is more general. See for full details. The displayed block is always rounded out to a full line at both ends. If no pattern is present, the entire file is displayed. Any line in the program that ends with the four characters is deleted from the source before inclusion, making it easy to write things like to find snippets like this and see only this: Also, inside the displayed text a line that ends will be highlighted in the display. A highlighting mark may have a suffix word, such as Such highlights are enabled only if the code invocation ends with "HL" followed by the word: The .code function may take one or more flags immediately preceding the filename. This command shows test.go in an editable text area: This command shows test.go with line numbers: play: The function "play" is the same as "code" but puts a button on the displayed source so the program can be run from the browser. Although only the selected text is shown, all the source is included in the HTML output so it can be presented to the compiler. link: Create a hyperlink. The syntax is 1 or 2 space-separated arguments. The first argument is always the HTTP URL. If there is a second argument, it is the text label to display for this link. image: The template uses the function "image" to inject picture files. The syntax is simple: 1 or 3 space-separated arguments. The first argument is always the file name. If there are more arguments, they are the height and width; both must be present, or substituted with an underscore. Replacing a dimension argument with the underscore parameter preserves the aspect ratio of the image when scaling. video: The template uses the function "video" to inject video files. The syntax is simple: 2 or 4 space-separated arguments. The first argument is always the file name. The second argument is always the file content-type. If there are more arguments, they are the height and width; both must be present, or substituted with an underscore. Replacing a dimension argument with the underscore parameter preserves the aspect ratio of the video when scaling. background: The template uses the function "background" to set the background image for a slide. The only argument is the file name of the image. caption: The template uses the function "caption" to inject figure captions. The text after ".caption" is embedded in a figcaption element after processing styling and links as in standard text lines. iframe: The function "iframe" injects iframes (pages inside pages). Its syntax is the same as that of image. html: The function html includes the contents of the specified file as unescaped HTML. This is useful for including custom HTML elements that cannot be created using only the slide format. It is your responsibility to make sure the included HTML is valid and safe. Presenter notes: Presenter notes may be enabled by appending the "-notes" flag when you run your "present" binary. This will allow you to open a second window by pressing 'N' from your browser displaying your slides. The second window is completely synced with your main window, except that presenter notes are only visible on the second window. Lines that begin with ": " are treated as presenter notes. Title of slide Some Text : Presenter notes (first paragraph) : Presenter notes (subsequent paragraph(s)) Notes may appear anywhere within the slide text. For example: Title of slide : Presenter notes (first paragraph) Some Text : Presenter notes (subsequent paragraph(s)) This has the same result as the example above.

Package gi is the top-level repository for the GoGi GUI framework. All of the code is in the sub-packages within this repository: * gist: css-based styling settings, including Color * girl: rendering library, can be used standalone, SVG compliant * gi: the main 2D GUI Node, Widgets, and Window * giv: more complex Views of Go data structures, supporting Model-View paradigm. * svg: full SVG rendering framework, used for Icons in gi. * gi3d: 3D rendering of a Scene within 2D windows -- full interactive 3D scenegraph. * histyle: text syntax-based highlighting styles -- used in giv.TextView * python: access all of GoGi from within Python using GoPy system.

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package chroma takes source code and other structured text and converts it into syntax highlighted HTML, ANSI- coloured text, etc. Chroma is based heavily on Pygments, and includes translators for Pygments lexers and styles. For more information, go here: https://github.com/alecthomas/chroma

Package syntax provides syntax highlighting for code. It currently uses a language-independent lexer and performs decently on JavaScript, Java, Ruby, Python, Go, and C.

Vox is a Go package designed to help make terminal/console applications more attractive. It is a collection of small helper functions that aid in printing various pieces of information to the console. - Various predefined and common printing tasks like printing property key/value pairs, result responses, etc. - Print JSON data with syntax highlighting - Easily print colorized output - Display real time progress bars for tasks - Easy helper functions for printing various types of messages: Alerts, errors, debug messages, etc. - Control the output and input streams to help during application testing. There are a number of output functions to print data to the screen with out without coloring. Most of the output functions accept an a series of string parts that are combined together. Color constants can be interlaced between these parts to color the output. There are also a number of "LogLevel" type functions that easily color the output. There are several helper functions for gathering input from the console. Vox offers pipelines as a way of configuring one or more output streams. Four built in pipelines are provided with the package: - ConsolePipeline - This is the default Pipeline set for any vox instance. This pipeline will present colored output to standard out. - FilePipeline - This pipeline will redirect all data to a local file. This pipeline uses plain output, without color codes. - TestPipeline - All output will be internally stored in a string slice and utility functions are provided to make accessing values easier. This pipeline should be used for unit tests. - WriterPipeline - This is a generic pipeline that allows you to specifiy any writer that implements the io.Writer interface. A testing pipeline is provided that directs all output into an internal string slice. It also provides utility functions to make accessing values easier. A Test helper function is provided to make this easier: You can use the `SendInput` function. SendInput must be called before any prompt function, so that the data is ready in the buffer when `Prompt` is called.