v0.12.1: woohoo, a new template function

This is a quiet one. Haven't had to change much. Guess that's a good sign?

features

• added a rawURL template which returns a template.URL
  • permits a value to be placed directly in a url="" attribute

v0.12.0: idk it's better now

there's a fancy new website at https://booklit.page!

refinements

• everything is godoc'd! this should make it a bit easier to use booklit APIs when writing plugins.

• the error UI style has been updated to match the website

• template rendering errors now use the new error UI

• styled sections no longer require a (name)-page.tmpl template

• the error page for referencing an unknown tag now suggests similar tags

• triple-curly-braces can now be used for single-line arguments, \like{{{this}}}!

• when \title is called twice in one section, an error will now be raised suggesting that the second \title should in its own \section{...}.

fixes

• when running in server mode, /foo/index.html will no longer be treated as /index.html

tweaks

• the chroma plugin will now set the HTML content as .Content in the styled template, rather than passing it as a partial.

• \reference no longer tries to match sections by their title - only tags, which is the documented and intended behavior.

• a log line will now be printed for each registered plugin

v0.11.0: to err is human

breaking changes

• the plugin system has been reverted back to the old reexec approach from pre-v0.8.0.

  the Go plugin package doesn't look like it will be getting Windows support any time soon, and the cross-compiled Darwin binaries stopped working, so really this just wasn't worth it.

  this means that all plugins must now go back from package main to package <whatever>. on the plus side, now you can import them again!

• a few methods on *booklit.Section now take an ast.Location argument, which is required for the "better error messages" feature below. plugins should typically adapt by passing it the value from the newly added .InvokeLocation field on the section object given to the plugin.

• booklit.Reference, booklit.Target, and booklit.Section now have Location fields which should similarly be populated by plugins which construct them, again in service of better error messages.

this diff shows a completed migration to v0.11.0, if you need a reference!

new features

errors are actually kinda helpful now!

the work here is multi-faceted:

• error messages have been reworded to be a bit less cryptic. (I think. Let me know.)

• the parser now preserves position information (i.e. line numbers), allowing it to be threaded through Booklit and returned in the errors.

• the CLI will render a helpful message, showing a snippet of the file where the error occurred, and even highlighting the exact region.

  

• the web UI will also render a helpful message, but in HTML (whoaaaaaaa).

  

• a PrettyError interface has been introduced, allowing plugins to leverage these pretty-error mechanisms.

bug fixes

• previously, \include-section in an inline \section would resolve its path relative to wherever booklit was run from. now it resolves paths relative to its outer section's file path, consistent with its use in a top-level document.

• booklit --help now exits successfully.

• the parser now accepts Windows-style CRLF line endings.

• the parser no longer requires a trailing linebreak at the end of the file.

• the parser no longer chokes on arguments containing a single linebreak:

  \foo{
  }
  

misc

• anchor tags now use the id attribute rather than name (thanks @jtarchie!)

v0.10.0: textual healing

breaking changes

• --tag has been renamed to --section-tag

new features

• --section-path has been added; if specified, the --in section will be
  loaded and then the given section path will be loaded and rendered with the
  --in section as its context.

  this is useful for things like release notes where the release notes aren't
  included into the main docs section but need it for resolving references.

• a basic text renderer has been added, using text/template instead of
  html/template and only including a few non-markup-specific templates. this
  is useful as a base for Markdown renderers.

• the joinLines function previously added in v0.9.0 has been moved to the
  new text renderer.

misc

• the 'parsing section' log line has been switched to debug level.

v0.9.0: out with --out, in with stdout

new features

• --out is now optional; if not specified, the section will be rendered to
  stdout.

• --tag has been added; if specified, the section will be loaded and then
  only the section specified by the given tag will be rendered.

misc

• the 'unknown template for (TYPE)' error condition is now returned earlier and
  returns an error specifying the name of the missing template.

• added a joinLines function, which is useful for implementing Markdown-style
  syntax where all lines but the first have to be inteded (e.g. lists).

v0.8.0: Go plugins and cache money

breaking changes

this release re-does how Booklit plugins are loaded. instead of generating and
compiling Go code on-the-fly, plugins are now loaded as Go
plugins.

the main difference is that plugins will have to be package main, and that
plugins are only loaded once on start. so if you've changed a plugin you'll
need to restart the Booklit server.

because Go plugins only work on Linux and OS X, support for Booklit plugins on
Windows is now dependent on upstream Go changes. sorry about that.

new features

• server mode will now render only the requested section, rather than
  rendering all sections and serving the requested file. this dramatically
  shortens the feedback cycle for large websites.

• section parsing is now cached based on file modification time. this also
  speeds things up quite a bit.

• HTML templates are also cached. you guessed it - things go faster.

misc

generally, the switch from compiling and re-exec'ing to Go plugins cleaned
things up quite a bit and made the above optimizations possible to implement.

v0.7.0: the next (or prev) release

new features

• added a few more helper methods to *booklit.Section which can be useful
  when templating:

  • NextSibling: returns the next sibling section, if any

  • Next: returns the first sub-section, if any, or the NextSibling

  • Prev: returns the previous sibling section, if any, or the parent section

  these are mainly in service of generating 'next/prev' links at the end of a
  section in order to guide the reader along to the rest of the content, in
  situations where the nav is separate and would be hard to notice

v0.6.0: searching for a release name

new features

• booklit can now be run with --save-search-index, which will generate a
  .json file alongside the generated output containing titles and content for
  each tag. this can be fed in to a client-side search engine to implement
  search functionality on the generated docs.

• added a few helper methods to *booklit.Section which can be useful when
  templating:

  • IsOrHasChild(*Section): useful when rendering a navigation tree, to
    determine whether to show a section as 'expanded'

  • Depth: analogous to PageDepth, this is the absolute depth of the
    section in the tree. this is exposed in the search index, as it can be
    useful to 'weigh' toplevel content higher when ranking the results.

  • SetTagAnchored: registers an anchored tag with additional content that
    can be shown in search results

• arbitrary content can now be specified to \target, like so:

  \target{some-tag}{This is a title}{This is arbitrary content.}
  

  this is mainly useful when building up search indexes, as it allows you to
  provide content to show for the given tag.

bug fixes

• the chroma plugin will no longer leave a <p> wrapping around code blocks

v0.5.0: i understood that reference

new features

• ambiguous references (those which can be satisfied by multiple tags) now
  result in an error, just like broken references (those matching no tags). to
  suppress the error, pass --allow-broken-references, as with broken
  references.

• broken and ambiguous references will result in a warning during compilation;
  this makes it easier to hunt them down and fix them while using
  --allow-broken-references.

• sped up build time when building with plugins, by using go install instead
  of go build

v0.4.0: the one that removes Block and Element

breaking changes

this release removes booklit.Block and booklit.Element. these two types of
booklit.Content were cop-outs that only served to allow adding CSS classes to
content that they wrapped. this leaked presentation/templating concerns into
content. you should use booklit.Styled instead.

the one use of booklit.Block, which was to force flow content to be block
content, is now localized to booklit.Styled, which was the only place it was
ever needed. there is a boolean field, Block, which can be set on
booklit.Styled to force it to be block content.