Skip to content

Conversation

@Mpdreamz
Copy link
Member

@Mpdreamz Mpdreamz commented Dec 19, 2024

This fixes #88 and properly parses code as regular blocks where its contents are treated as plain text.

Prior to this code blocks behaved like directives and we did a few hacks to get the rendered markdown to display as text.

Had to re-implement supporting substitutions in code blocks since we can no longer rely on SubstitutionBlock being part of its AST.

As for code callouts:

```yaml
project:
  title: MyST Markdown 
  github: https://github.com/jupyter-book/mystmd
  license:
    code: MIT
    content: CC-BY-4.0 <1>
  subject: MyST Markdown 
```

1. The license

A code block can include <\d+> at the end to indicate code callouts. A code block with this style of callouts needs to be followed by an ordered list with an equal amount of items as called out. Otherwise the docs-builder will throw an error.

Image

magic mode

We will also support 'magic' callouts:

```csharp
var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
```

Here nothing needs to be numbered and // Set up the api key will be removed from the code block and rendered as the first callout.

This currently works for comments starting with // and # which will cover the majority of languages.

Note the comments have the follow code to be hoisted as a callout.

```csharp
// THIS IS NOT A CALLOUT
var apiKey = new ApiKey("<API_KEY>"); // THIS IS
var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
```

This style will allow the callouts to render correctly and for the embedded code to be still syntactically correct.

@Mpdreamz Mpdreamz merged commit 6ddd7a6 into main Dec 19, 2024
4 checks passed
@Mpdreamz Mpdreamz deleted the feature/code-callouts branch December 19, 2024 18:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Migration tooling] Code callouts Isolate Code parser from Directives [Meta] Code directive capabilities code directive

2 participants