goldmark

# Instructions for agents

## Testing instructions
- use `make test` to run tests
- use `make lint` to run linters

## Benchmark instructions
- use `make bench` to run benchmarks
  - this will output cpu profiler data to `cpu.pprof` file

## Coding conventions
- Make sure to pass `make lint`
- Use `util.StringToReadOnlyBytes` and `util.ReadOnlyBytesToString` when converting between readonly strings and readonly byte slices to avoid unnecessary allocations.
- Before making changes, you must run `make bench`. After making changes, you should run `make bench` again to compare the performance before and after your changes. 
  - If your changes cause a significant performance regression, you should analyze `cpu.pprof` to identify the bottlenecks and optimize your code accordingly.

## Key point of CommonMark spec
- In most cases, punctuation characters can be escaped with a backslash (`\`) to prevent them from being interpreted as Markdown syntax. For example, `\*` will render as `*` instead of starting an emphasis.
- Spec defines sets of character categories. Use `util` package to check if a character belongs to a specific category. For example, `util.IsPunct` can be used to check if a character is a punctuation character. DO NOT use standard library functions like `unicode.IsPunct` as they may not cover all cases defined in the CommonMark spec.
- Most of inline elements (like emphasis, links, etc.) can exist within multiple lines. And they can be nested. So inline elements probably have multiple divided segments:

  ```markdown
  > [lin
  > nk](https://example.com)
  ```

  In this case, the link element has two divided segments: `lin` and `nk`. When parsing, you should keep track of these segments and combine them when necessary. This kind of elements should have `text.MultiLineValue` instead of `text.SingleLineValue`.
- Paragraph rendering can be changed by parent elements. For example, a paragraph inside a tight list item should not have `<p>` tags, while a paragraph inside a block quote should have `<p>` tags.
- Tabs can be 1,2,3,4 spaces or raw tab character, depending on its position. When parsing block elements, you should aware of this and calculate the correct indentation level.

## Commit messages
- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format for commit messages.
  - Use sub package name as the scope. For example, if you are making changes to `parser` package, your commit message should be like:
    ```
    fix(parser): fix parsing of nested links
    ```
- **SHOULD NOT** use `fix #<issue_number>` in commit messages. goldmark has multiple major versions. In most cases, we can not close issues in 1 commit. Instead, you should use `Refs: #<issue_number>` like the following:
  ```
  fix(parser): fix parsing of nested links

  Refs: #123
  ```

More agent context in yuin/goldmark

One other file this repository gives its agents.