github.com/linchen2chris/hugo@v0.0.0-20230307053224-cec209389705/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  type LinkContext interface {
    35  	// The Page being rendered.
    36  	Page() any
    37  
    38  	// The link URL.
    39  	Destination() string
    40  
    41  	// The link title attribute.
    42  	Title() string
    43  
    44  	// The rendered (HTML) text.
    45  	Text() hstring.RenderedString
    46  
    47  	// The plain variant of Text.
    48  	PlainText() string
    49  }
    50  
    51  type ImageLinkContext interface {
    52  	LinkContext
    53  
    54  	// Returns true if this is a standalone image and the config option
    55  	// markup.goldmark.parser.wrapStandAloneImageWithinParagraph is disabled.
    56  	IsBlock() bool
    57  
    58  	// Zero-based ordinal for all the images in the current document.
    59  	Ordinal() int
    60  }
    61  
    62  // CodeblockContext is the context passed to a code block render hook.
    63  type CodeblockContext interface {
    64  	AttributesProvider
    65  	text.Positioner
    66  
    67  	// Chroma highlighting processing options. This will only be filled if Type is a known Chroma Lexer.
    68  	Options() map[string]any
    69  
    70  	// The type of code block. This will be the programming language, e.g. bash, when doing code highlighting.
    71  	Type() string
    72  
    73  	// The text between the code fences.
    74  	Inner() string
    75  
    76  	// Zero-based ordinal for all code blocks in the current document.
    77  	Ordinal() int
    78  
    79  	// The owning Page.
    80  	Page() any
    81  }
    82  
    83  type AttributesOptionsSliceProvider interface {
    84  	AttributesSlice() []attributes.Attribute
    85  	OptionsSlice() []attributes.Attribute
    86  }
    87  
    88  type LinkRenderer interface {
    89  	RenderLink(cctx context.Context, w io.Writer, ctx LinkContext) error
    90  	identity.Provider
    91  }
    92  
    93  type CodeBlockRenderer interface {
    94  	RenderCodeblock(cctx context.Context, w hugio.FlexiWriter, ctx CodeblockContext) error
    95  	identity.Provider
    96  }
    97  
    98  type IsDefaultCodeBlockRendererProvider interface {
    99  	IsDefaultCodeBlockRenderer() bool
   100  }
   101  
   102  // HeadingContext contains accessors to all attributes that a HeadingRenderer
   103  // can use to render a heading.
   104  type HeadingContext interface {
   105  	// Page is the page containing the heading.
   106  	Page() any
   107  	// Level is the level of the header (i.e. 1 for top-level, 2 for sub-level, etc.).
   108  	Level() int
   109  	// Anchor is the HTML id assigned to the heading.
   110  	Anchor() string
   111  	// Text is the rendered (HTML) heading text, excluding the heading marker.
   112  	Text() hstring.RenderedString
   113  	// PlainText is the unrendered version of Text.
   114  	PlainText() string
   115  
   116  	// Attributes (e.g. CSS classes)
   117  	AttributesProvider
   118  }
   119  
   120  // HeadingRenderer describes a uniquely identifiable rendering hook.
   121  type HeadingRenderer interface {
   122  	// Render writes the rendered content to w using the data in w.
   123  	RenderHeading(cctx context.Context, w io.Writer, ctx HeadingContext) error
   124  	identity.Provider
   125  }
   126  
   127  // ElementPositionResolver provides a way to resolve the start Position
   128  // of a markdown element in the original source document.
   129  // This may be both slow and approximate, so should only be
   130  // used for error logging.
   131  type ElementPositionResolver interface {
   132  	ResolvePosition(ctx any) text.Position
   133  }
   134  
   135  type RendererType int
   136  
   137  const (
   138  	LinkRendererType RendererType = iota + 1
   139  	ImageRendererType
   140  	HeadingRendererType
   141  	CodeBlockRendererType
   142  )
   143  
   144  type GetRendererFunc func(t RendererType, id any) any