github.com/anakojm/hugo-katex@v0.0.0-20231023141351-42d6f5de9c0b/markup/converter/hooks/hooks.go (about)

     1  // Copyright 2019 The Hugo Authors. All rights reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  // http://www.apache.org/licenses/LICENSE-2.0
     7  //
     8  // Unless required by applicable law or agreed to in writing, software
     9  // distributed under the License is distributed on an "AS IS" BASIS,
    10  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    11  // See the License for the specific language governing permissions and
    12  // limitations under the License.
    13  
    14  package hooks
    15  
    16  import (
    17  	"context"
    18  	"io"
    19  
    20  	"github.com/gohugoio/hugo/common/hugio"
    21  	"github.com/gohugoio/hugo/common/text"
    22  	"github.com/gohugoio/hugo/common/types/hstring"
    23  	"github.com/gohugoio/hugo/identity"
    24  	"github.com/gohugoio/hugo/markup/internal/attributes"
    25  )
    26  
    27  var _ AttributesOptionsSliceProvider = (*attributes.AttributesHolder)(nil)
    28  
    29  type AttributesProvider interface {
    30  	// Attributes passed in from Markdown (e.g. { attrName1=attrValue1 attrName2="attr Value 2" }).
    31  	Attributes() map[string]any
    32  }
    33  
    34  // LinkContext is the context passed to a link render hook.
    35  type LinkContext interface {
    36  	// The Page being rendered.
    37  	Page() any
    38  
    39  	// The link URL.
    40  	Destination() string
    41  
    42  	// The link title attribute.
    43  	Title() string
    44  
    45  	// The rendered (HTML) text.
    46  	Text() hstring.RenderedString
    47  
    48  	// The plain variant of Text.
    49  	PlainText() string
    50  }
    51  
    52  // ImageLinkContext is the context passed to a image link render hook.
    53  type ImageLinkContext interface {
    54  	LinkContext
    55  
    56  	// Returns true if this is a standalone image and the config option
    57  	// markup.goldmark.parser.wrapStandAloneImageWithinParagraph is disabled.
    58  	IsBlock() bool
    59  
    60  	// Zero-based ordinal for all the images in the current document.
    61  	Ordinal() int
    62  }
    63  
    64  // CodeblockContext is the context passed to a code block render hook.
    65  type CodeblockContext interface {
    66  	AttributesProvider
    67  	text.Positioner
    68  
    69  	// Chroma highlighting processing options. This will only be filled if Type is a known Chroma Lexer.
    70  	Options() map[string]any
    71  
    72  	// The type of code block. This will be the programming language, e.g. bash, when doing code highlighting.
    73  	Type() string
    74  
    75  	// The text between the code fences.
    76  	Inner() string
    77  
    78  	// Zero-based ordinal for all code blocks in the current document.
    79  	Ordinal() int
    80  
    81  	// The owning Page.
    82  	Page() any
    83  }
    84  
    85  type AttributesOptionsSliceProvider interface {
    86  	AttributesSlice() []attributes.Attribute
    87  	OptionsSlice() []attributes.Attribute
    88  }
    89  
    90  type LinkRenderer interface {
    91  	RenderLink(cctx context.Context, w io.Writer, ctx LinkContext) error
    92  	identity.Provider
    93  }
    94  
    95  type CodeBlockRenderer interface {
    96  	RenderCodeblock(cctx context.Context, w hugio.FlexiWriter, ctx CodeblockContext) error
    97  	identity.Provider
    98  }
    99  
   100  type IsDefaultCodeBlockRendererProvider interface {
   101  	IsDefaultCodeBlockRenderer() bool
   102  }
   103  
   104  // HeadingContext contains accessors to all attributes that a HeadingRenderer
   105  // can use to render a heading.
   106  type HeadingContext interface {
   107  	// Page is the page containing the heading.
   108  	Page() any
   109  	// Level is the level of the header (i.e. 1 for top-level, 2 for sub-level, etc.).
   110  	Level() int
   111  	// Anchor is the HTML id assigned to the heading.
   112  	Anchor() string
   113  	// Text is the rendered (HTML) heading text, excluding the heading marker.
   114  	Text() hstring.RenderedString
   115  	// PlainText is the unrendered version of Text.
   116  	PlainText() string
   117  
   118  	// Attributes (e.g. CSS classes)
   119  	AttributesProvider
   120  }
   121  
   122  // HeadingRenderer describes a uniquely identifiable rendering hook.
   123  type HeadingRenderer interface {
   124  	// RenderHeading writes the rendered content to w using the data in w.
   125  	RenderHeading(cctx context.Context, w io.Writer, ctx HeadingContext) error
   126  	identity.Provider
   127  }
   128  
   129  // ElementPositionResolver provides a way to resolve the start Position
   130  // of a markdown element in the original source document.
   131  // This may be both slow and approximate, so should only be
   132  // used for error logging.
   133  type ElementPositionResolver interface {
   134  	ResolvePosition(ctx any) text.Position
   135  }
   136  
   137  type RendererType int
   138  
   139  const (
   140  	LinkRendererType RendererType = iota + 1
   141  	ImageRendererType
   142  	HeadingRendererType
   143  	CodeBlockRendererType
   144  )
   145  
   146  type GetRendererFunc func(t RendererType, id any) any