Potential incorrect Markdown link syntax

[ajatprabha]

I'm working on something where I need to use the Markdown generated from gomarkoc, and then use the result in a Docusaurus documentation project.

However, creating a build fails, because the Link is probably wrong, AFAIK, I have seen the syntax to be [text](link) and not [text](<link>).

gomarkdoc/format/formatcore/base.go

Line 101 in e62c5ab

return fmt.Sprintf("[%s](<%s>)", Escape(text), href)

GitHub Docs Ref: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links

Is there any particular reason for doing this? If not, can we fix this?

Failing use-case: Link

Error:

npm run build

> [email protected] build
> docusaurus build

[INFO] [en] Creating an optimized production build...
Browserslist: caniuse-lite is outdated. Please run:
  npx browserslist@latest --update-db
  Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
[info] [webpackbar] Compiling Client
[info] [webpackbar] Compiling Server
Browserslist: caniuse-lite is outdated. Please run:
  npx browserslist@latest --update-db
  Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
[success] [webpackbar] Client: Compiled with some errors in 16.3[4](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:5)s


SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/SDK.md: Unexpected token (1[5](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:6)4:0)
  152 | <a name="ExponentialStartStrategy"></a>
Error:  Client bundle compiled with errors therefore further build is impossible.
  153 | ## func [ExponentialStartStrategy](<https://github.com/gojek/courier-go/blob/main/exp_starter.go#L37>)
> 154 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`func ExponentialStartStrategy(ctx context.Context, c interface{ Start() error }, opts ...StartOption)
      | ^
  155 | `}</code></pre>
  15[6](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:7) | <p>{`ExponentialStartStrategy will keep attempting to call Client.Start in the background and retry on error, it will never exit unless the context used to invoke is cancelled. This will NOT stop the client, that is the responsibility of caller.`}</p>
  15[7](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:8) | <a name="Version"></a>
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/otelcourier.md: Unexpected token (52:0)
  50 | <a name="DisableCallbackTracing"></a>
  51 | ## func [DisableCallbackTracing](<https://github.com/gojek/courier-go/blob/main/otelcourier/options.go#L59>)
> 52 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`func DisableCallbackTracing(opts *traceOptions)
     | ^
  53 | `}</code></pre>
  54 | <p>{`DisableCallbackTracing disables implicit tracing on subscription callbacks.`}</p>
  55 | <a name="DisablePublisherTracing"></a>
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/backoff.md: Unexpected token (29:0)
  27 | <a name="Exponential"></a>
  2[8](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:9) | ## type [Exponential](<https://github.com/gojek/courier-go/blob/main/xds/backoff/backoff.go#L27-L30>)
> 2[9](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:10) | <p>{`Exponential implements exponential backoff algorithm as defined in `}<a parentName="p" {...{"href":"https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md"}}>{`https://github.com/grpc/grpc/blob/master/doc/connection-backoff.md`}</a>{`.`}</p>
     | ^
  30 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Exponential struct {
  31 |     // Config contains all options to configure the backoff algorithm.
  32 |     Config grpcbackoff.Config
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/bootstrap.md: Unexpected token (31:0)
  29 | <a name="Config"></a>
  30 | ## type [Config](<https://github.com/gojek/courier-go/blob/main/xds/bootstrap/bootstrap.go#L55-L58>)
> 31 | <p>{`Config provides the xDS client with several key bits of information that it requires in its interaction with the management server. The Config is initialized from the bootstrap file.`}</p>
     | ^
  32 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Config struct {
  33 |     // XDSServer is the management server to connect to.
  34 |     XDSServer *ServerConfig \`json:"xds_server"\`
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/log.md: Unexpected token (26:0)
  24 | <a name="Logger"></a>
  25 | ## type [Logger](<https://github.com/gojek/courier-go/blob/main/xds/log/logger.go#L4-L[11](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:12)>)
> 26 | <p>{`Logger is used to log messages of info, error and debug levels`}</p>
     | ^
  27 | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Logger interface {
  28 |     // Info is used to log info level log messages
  29 |     Info(msg string, keysAndValues ...interface{})
SyntaxError: /home/runner/work/courier-go/courier-go/docs/docs/sdk/xds/xDS.md: Unexpected token (34:0)
  [32](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:33) | <a name="Client"></a>
  [33](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:34) | ## type [Client](<https://github.com/gojek/courier-go/blob/main/xds/client.go#L69-L80>)
> 34 | <p>{`Client performs the actual ADS RPCs using the ADS v3 API. It creates an ADS stream on which the xdsTarget resources are received.`}</p>
     | ^
  [35](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:36) | <pre><code parentName="pre" {...{"className":"language-go"}}>{`type Client struct {
  [36](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:37) |     // contains filtered or unexported fields
  [37](https://github.com/gojek/courier-go/actions/runs/5461645779/jobs/9939911784#step:5:38) | }
Error: Process completed with exit code 1.

[ajatprabha]

I verified locally that correcting the syntax does result in a successful build.
Is there a way to change this behaviour behind a cli flag maybe?

[princjef]

Hey @ajatprabha, thanks for looking into this. The [](<>) syntax was pulled from the GitHub Flavored Markdown spec and does work correctly when used within GitHub. I'm not familiar with Docusaurus - does it differ from GFM at all or is it designed to support identical syntax? If it's the former then I'd be open to including an additional formatter that is specific to the format that Docusaurus expects.

Lacking the ability to do that, a CLI flag seems like a possible option. Removing the <> would likely cause little impact to people using the tool today, but there are some edge cases for links that aren't possible without the <>

[ajatprabha]

Docusaurus uses MDX which according to docs is a superset of standard Markdown syntax supporting JSX as well.

Not sure how much effort it will be to add a new flavour for this.

Ref: https://docusaurus.io/docs/markdown-features

[princjef]

Adding new format types isn't too bad (most code has a shared core and tests are generated from snapshots anyway). It looks like the specific problem with MDX here is not actually the base markdown syntax (CommonMark is the base spec they reference and it supports <> around link destinations), but rather their note about needing to escape < and > to avoid conflicts with the JSX syntax.

Are there any other features of the github format that don't make sense for your use case? Things like the repository code links and accordion are pretty specific to how GFM wants to render things and don't carry over to the plain format for instance.

I've considered adding a CommonMark format in the past and have only held off because nobody has asked for it. I'd be alright with throwing an MDX format in with a couple tweaks while I'm at it if that can make the integration more seamless.