Documentation

Overview

    Package render contains conversions from a processed Booklit section into a rendered format such as plaintext or HTML, either for serving in a browser or for writing to files on disk.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var HTMLFuncs = template.FuncMap{
    	"render": func(booklit.Content) (template.HTML, error) {
    		return "", errors.New("render stubbed out")
    	},
    
    	"url": func(tag booklit.Tag) string {
    		return sectionURL("html", tag.Section, tag.Anchor)
    	},
    
    	"stripAux": booklit.StripAux,
    
    	"rawHTML": func(con booklit.Content) template.HTML {
    		return template.HTML(con.String())
    	},
    
    	"walkContext": func(current *booklit.Section, section *booklit.Section) WalkContext {
    		return WalkContext{
    			Current: current,
    			Section: section,
    		}
    	},
    
    	"headerDepth": func(con *booklit.Section) int {
    		depth := con.PageDepth() + 1
    		if depth > 6 {
    			depth = 6
    		}
    
    		return depth
    	},
    }

      HTMLFuncs is the set of functions available to all templates.

      See https://booklit.page/html-renderer.html#template-functions for more information.

      View Source
      var TextFuncs = template.FuncMap{
      	"render": func(booklit.Content) (string, error) {
      		return "", errors.New("render stubbed out")
      	},
      
      	"url": func(ext string, tag booklit.Tag) (string, error) {
      		return "", errors.New("url stubbed out")
      	},
      
      	"htmlURL": func(tag booklit.Tag) string {
      		return sectionURL("html", tag.Section, tag.Anchor)
      	},
      
      	"stripAux": booklit.StripAux,
      
      	"joinLines": func(prefix string, str string) string {
      		return strings.Join(strings.Split(str, "\n"), "\n"+prefix)
      	},
      }

        TextFuncs is the set of functions available to all templates.

        Functions

        This section is empty.

        Types

        type Engine

        type Engine interface {
        	// RenderSection writes the given section to the writer.
        	RenderSection(io.Writer, *booklit.Section) error
        
        	// The canonical file extension for files written by the engine,
        	// without the leading dot.
        	FileExtension() string
        
        	// The URL to reference rendered content for a given tag.
        	URL(booklit.Tag) string
        }

          Engine is the primary type for rendering sections.

          type HTMLEngine

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

            HTMLEngine renders sections as HTML using Go's html/template system.

            func NewHTMLEngine

            func NewHTMLEngine() *HTMLEngine

              NewHTMLEngine constructs a new HTMLEngine with the basic set of HTML templates bundled with Booklit.

              func (*HTMLEngine) FileExtension

              func (engine *HTMLEngine) FileExtension() string

                FileExtension returns "html".

                func (*HTMLEngine) LoadTemplates

                func (engine *HTMLEngine) LoadTemplates(templatesDir string) error

                  LoadTemplates loads all *.tmpl files in the specified directory.

                  func (*HTMLEngine) RenderSection

                  func (engine *HTMLEngine) RenderSection(out io.Writer, con *booklit.Section) error

                    RenderSection renders the section to the writer using page.tmpl.

                    If the section has Style set and a template named (Style)-page.tmpl exists it will be used instead.

                    func (*HTMLEngine) URL

                    func (engine *HTMLEngine) URL(tag booklit.Tag) string

                      URL returns the HTML file name with an anchor if present.

                      func (*HTMLEngine) VisitDefinitions

                      func (engine *HTMLEngine) VisitDefinitions(con booklit.Definitions) error

                        VisitDefinitions renders con using definitions.tmpl.

                        func (*HTMLEngine) VisitImage

                        func (engine *HTMLEngine) VisitImage(con booklit.Image) error

                          VisitImage renders con using image.tmpl.

                          func (engine *HTMLEngine) VisitLink(con booklit.Link) error

                            VisitLink renders con using link.tmpl.

                            func (*HTMLEngine) VisitList

                            func (engine *HTMLEngine) VisitList(con booklit.List) error

                              VisitList renders con using list.tmpl.

                              func (*HTMLEngine) VisitParagraph

                              func (engine *HTMLEngine) VisitParagraph(con booklit.Paragraph) error

                                VisitParagraph renders con using paragraph.tmpl.

                                func (*HTMLEngine) VisitPreformatted

                                func (engine *HTMLEngine) VisitPreformatted(con booklit.Preformatted) error

                                  VisitPreformatted renders con using preformatted.tmpl.

                                  func (*HTMLEngine) VisitReference

                                  func (engine *HTMLEngine) VisitReference(con *booklit.Reference) error

                                    VisitReference renders con using reference.tmpl.

                                    func (*HTMLEngine) VisitSection

                                    func (engine *HTMLEngine) VisitSection(con *booklit.Section) error

                                      VisitSection renders con using section.tmpl.

                                      If the section has Style set and a template named (Style).tmpl exists it will be used instead.

                                      func (*HTMLEngine) VisitSequence

                                      func (engine *HTMLEngine) VisitSequence(con booklit.Sequence) error

                                        VisitSequence renders con using sequence.tmpl.

                                        func (*HTMLEngine) VisitString

                                        func (engine *HTMLEngine) VisitString(con booklit.String) error

                                          VisitString renders con using string.tmpl.

                                          func (*HTMLEngine) VisitStyled

                                          func (engine *HTMLEngine) VisitStyled(con booklit.Styled) error

                                            VisitStyled renders con using (Style).tmpl.

                                            func (*HTMLEngine) VisitTable

                                            func (engine *HTMLEngine) VisitTable(con booklit.Table) error

                                              VisitTable renders con using table.tmpl.

                                              func (*HTMLEngine) VisitTableOfContents

                                              func (engine *HTMLEngine) VisitTableOfContents(con booklit.TableOfContents) error

                                                VisitTableOfContents renders con using toc.tmpl.

                                                func (*HTMLEngine) VisitTarget

                                                func (engine *HTMLEngine) VisitTarget(con booklit.Target) error

                                                  VisitTarget renders con using target.tmpl.

                                                  type SearchDocument

                                                  type SearchDocument struct {
                                                  	// The tag's URL.
                                                  	Location string `json:"location"`
                                                  
                                                  	// The title of the tag.
                                                  	Title string `json:"title"`
                                                  
                                                  	// The text content for the tag, or the section's text if the tag
                                                  	// does not have its own content.
                                                  	Text string `json:"text"`
                                                  
                                                  	// The depth of the tag's section.
                                                  	Depth int `json:"depth"`
                                                  
                                                  	// The containing section's primary tag.
                                                  	SectionTag string `json:"section_tag"`
                                                  }

                                                    SearchDocument contains data useful for implementing inline search.

                                                    type SearchIndex

                                                    type SearchIndex map[string]SearchDocument

                                                      SearchIndex is a mapping from tag names to a summary useful for inline search.

                                                      type TextEngine

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

                                                        TextEngine renders sections as plaintext using Go's text/template system.

                                                        Text templates may be provided to generate e.g. Markdown or other plaintext formats.

                                                        func NewTextEngine

                                                        func NewTextEngine(fileExtension string) *TextEngine

                                                          NewTextEngine constructs a new TextEngine with the basic set of text templates bundled with Booklit.

                                                          A file extension must be provided, e.g. "md" for Markdown.

                                                          func (*TextEngine) FileExtension

                                                          func (engine *TextEngine) FileExtension() string

                                                            FileExtension returns the configured file extension.

                                                            func (*TextEngine) LoadTemplates

                                                            func (engine *TextEngine) LoadTemplates(templatesDir string) error

                                                              LoadTemplates loads all *.tmpl files in the specified directory.

                                                              func (*TextEngine) RenderSection

                                                              func (engine *TextEngine) RenderSection(out io.Writer, con *booklit.Section) error

                                                                RenderSection renders the section to the writer using page.tmpl.

                                                                If the section has Style set and a template named (Style)-page.tmpl exists it will be used instead.

                                                                func (*TextEngine) URL

                                                                func (engine *TextEngine) URL(tag booklit.Tag) string

                                                                  URL returns the file name using te configured file extension, with an anchor if present.

                                                                  func (*TextEngine) VisitDefinitions

                                                                  func (engine *TextEngine) VisitDefinitions(con booklit.Definitions) error

                                                                    VisitDefinitions renders con using definitions.tmpl.

                                                                    func (*TextEngine) VisitImage

                                                                    func (engine *TextEngine) VisitImage(con booklit.Image) error

                                                                      VisitImage renders con using image.tmpl.

                                                                      func (engine *TextEngine) VisitLink(con booklit.Link) error

                                                                        VisitLink renders con using link.tmpl.

                                                                        func (*TextEngine) VisitList

                                                                        func (engine *TextEngine) VisitList(con booklit.List) error

                                                                          VisitList renders con using list.tmpl.

                                                                          func (*TextEngine) VisitParagraph

                                                                          func (engine *TextEngine) VisitParagraph(con booklit.Paragraph) error

                                                                            VisitParagraph renders con using paragraph.tmpl.

                                                                            func (*TextEngine) VisitPreformatted

                                                                            func (engine *TextEngine) VisitPreformatted(con booklit.Preformatted) error

                                                                              VisitPreformatted renders con using preformatted.tmpl.

                                                                              func (*TextEngine) VisitReference

                                                                              func (engine *TextEngine) VisitReference(con *booklit.Reference) error

                                                                                VisitReference renders con using reference.tmpl.

                                                                                func (*TextEngine) VisitSection

                                                                                func (engine *TextEngine) VisitSection(con *booklit.Section) error

                                                                                  VisitSection renders con using section.tmpl.

                                                                                  If the section has Style set and a template named (Style).tmpl exists it will be used instead.

                                                                                  func (*TextEngine) VisitSequence

                                                                                  func (engine *TextEngine) VisitSequence(con booklit.Sequence) error

                                                                                    VisitSequence renders con using sequence.tmpl.

                                                                                    func (*TextEngine) VisitString

                                                                                    func (engine *TextEngine) VisitString(con booklit.String) error

                                                                                      VisitString renders con using string.tmpl.

                                                                                      func (*TextEngine) VisitStyled

                                                                                      func (engine *TextEngine) VisitStyled(con booklit.Styled) error

                                                                                        VisitStyled renders con using (Style).tmpl.

                                                                                        func (*TextEngine) VisitTable

                                                                                        func (engine *TextEngine) VisitTable(con booklit.Table) error

                                                                                          VisitTable renders con using table.tmpl.

                                                                                          func (*TextEngine) VisitTableOfContents

                                                                                          func (engine *TextEngine) VisitTableOfContents(con booklit.TableOfContents) error

                                                                                            VisitTableOfContents renders con using toc.tmpl.

                                                                                            func (*TextEngine) VisitTarget

                                                                                            func (engine *TextEngine) VisitTarget(con booklit.Target) error

                                                                                              VisitTarget renders con using target.tmpl.

                                                                                              type WalkContext

                                                                                              type WalkContext struct {
                                                                                              	Current *booklit.Section
                                                                                              	Section *booklit.Section
                                                                                              }

                                                                                                WalkContext is a utility type constructed via the walkContext template function.

                                                                                                type Writer

                                                                                                type Writer struct {
                                                                                                	Engine Engine
                                                                                                
                                                                                                	Destination string
                                                                                                }

                                                                                                  Writer writes rendered content using an Engine to the given destination.

                                                                                                  func (Writer) WriteSearchIndex

                                                                                                  func (writer Writer) WriteSearchIndex(section *booklit.Section, path string) error

                                                                                                    WriteSearchIndex generates and writes a SearchIndex in JSON format to the given path within the destination.

                                                                                                    func (Writer) WriteSection

                                                                                                    func (writer Writer) WriteSection(section *booklit.Section) error

                                                                                                      WriteSection renders the given section to disk if it has no parent or if its parent is configured with SplitSections.

                                                                                                      After rendering, WriteSection recurses to the section's Children.

                                                                                                      Directories

                                                                                                      Path Synopsis
                                                                                                      Code generated for package html by go-bindata DO NOT EDIT.
                                                                                                      Code generated for package html by go-bindata DO NOT EDIT.
                                                                                                      Code generated for package text by go-bindata DO NOT EDIT.
                                                                                                      Code generated for package text by go-bindata DO NOT EDIT.