Goldmark Extension v1 to v2 Migration

migrate-goldmark-extension-v1-to-v2

Description

This skill helps you migrate a goldmark (https://github.com/yuin/goldmark) extension from version 1 to version 2. It provides guidance on the changes needed to update your project to be compatible with the new version of goldmark.

Knowledges

• CommonMark key points : List of key points of CommonMark spec that you should be aware of when implementing a goldmark extension.
• Breaking changes in v2 : List of breaking changes in goldmark v2 that you should be aware of when migrating your extension from v1 to v2.
• How to create an extension : Guide on how to create a goldmark extension in v2, including the new extension pattern and how to implement parser and renderer extensions.

Migration steps

Overview of the migration process

• Create a migration plan for the extension.
• MUST ask human to confirm that the migration plan is acceptable before proceeding with the migration.
• MUST ask human to how to test the extension after migration before proceeding with the migration.
  • e.g. : "How do you want to test the extension after migration? Do you have any test cases or examples that you want to use for testing?"
• Execute the migration plan to update the extension code to be compatible with goldmark v2.
• Update the test cases to ensure that the extension works as expected with goldmark v2.
• Test the extension with goldmark v2 to ensure that it works as expected. If there are any issues, fix them and re-test until the extension works as expected.
• Update the documentation to reflect any changes made during the migration process.

Create a migration plan

Task

• Make sure you have read and understood the Breaking changes in v2 document.
• Make sure you have read and understood the How to create an extension document.
• You create a ./features/goldmark-migration-plan.md file that contains a migration plan for the extension.

Key points to consider when migrating your extension

Extension options

• If the extension uses "unified" options for both parser and renderer, they should be split into separate options for each.
  • e.g. :
    • v1

      type Option interface {
          myOption()
      }
      
      type ParserOption interface {
          Option
          applyParserOption(*parserConfig)
      }
      
      type RendererOption interface {
          Option
          applyRendererOption(*rendererConfig)
      }
      
      func New(opts ...Option) goldmark.Extender { // takes unified options
          // ...
      }

    • v2

      type ParserOption interface {
          applyParserOption(*parserConfig)
      }
      
      type HTMLRendererOption interface { // explicitly named for **HTML**
          applyRendererOption(*htmlRendererConfig) // you can access the shared renderer config like `XHTML` or `Unsafe` in the renderer config
      }
      
      func NewParser(opts ...ParserOption) parser.Extension { // takes parser options
          // ...
      }
      
      var Parser = NewParser() // Default instance of parser extension
      
      func NewHTMLRenderer(opts ...HTMLRendererOption) html.Extension { // takes renderer options
          // ...
      }
      
      var HTMLRenderer = NewHTMLRenderer() // Default instance of renderer extension

AST nodes

• use text.Value(single line), text.MultiLineValue(multi-line) instead of []byte for values that can be parsed from source text in inline AST nodes.
  • In your parser, you must choose text.Decoder implementation to decode the source value
    • text.IdentityDecoder : for raw contents like inline HTMLs, inline code, etc.
    • reader.Decoder : other contents like text, links, etc. This decoder decodes entity references, \ escapes, etc.
  • In most cases, you will choose text.Decoder. DO NOT use text.IdentityDecoder unless you have a clear intention to do so.
• use text.Lines instead of []text.Segment for values in block AST nodes that have raw contents like HTML blocks, code blocks, etc.
• Properties in AST Dump should be text.Value as possible.
  • e.g.
    • OK:

      // Dump implements Node.Dump.
      func (n *Text) Dump(_ []byte) *NodeDump {
          m := map[string]any{
              "Value": n.Value, // text.Value
          }
          fs := textFlagsString(n.flags)
          if len(fs) != 0 {
              m["Flags"] = fs
          }
          return NewNodeDump(n, m)
      }

    • Not OK:

      // Dump implements Node.Dump.
      func (n *Text) Dump(source []byte) *NodeDump {
          m := map[string]any{
              "Value": n.Value.Str(source), // string
          }
          fs := textFlagsString(n.flags)
          if len(fs) != 0 {
              m["Flags"] = fs
          }
          return NewNodeDump(n, m)
      }

• In v2, attribute values are text.Value which has almost the same specification as HTML attributes.
  • Therefore, if the project were using non-string attributes in v1, human must decide on one of the following policies:
    • Use the goldmark_v1_attribute build tag to continue using v1 attributes as they are.
    • Convert attribute values to strings to comply with the v2 specification.
  • MUST ask human to decide on one of the above policies before proceeding with the migration.