8000 Potential incorrect Markdown link syntax · Issue #106 · princjef/gomarkdoc · GitHub
[go: up one dir, main page]

Skip to content

Potential incorrect Markdown link syntax #106

Open

Description

@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>).

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:

Details
npm run build

> courier@0.0.0 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
8000
 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.

Activity

  1. ajatprabha commented on Jul 5, 2023

    @ajatprabha
    Author

    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?

  2. princjef commented on Aug 18, 2023

    @princjef
    Owner

    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 <>

  3. ajatprabha commented on Aug 18, 2023

    @ajatprabha
    Author

    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

  4. princjef commented on Aug 19, 2023

    @princjef
    Owner

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0