Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for code callouts #118

Merged
merged 4 commits into from
Dec 19, 2024
Merged

Add support for code callouts #118

merged 4 commits into from
Dec 19, 2024

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