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

[Migration tooling] Code callouts #102

Closed
Tracked by #56
bmorelli25 opened this issue Dec 10, 2024 · 2 comments · Fixed by #118
Closed
Tracked by #56

[Migration tooling] Code callouts #102

bmorelli25 opened this issue Dec 10, 2024 · 2 comments · Fixed by #118
Labels
authoring Relates to our markdown parser

Comments

@bmorelli25
Copy link
Member

bmorelli25 commented Dec 10, 2024

Summary

Follow-up to #7.

Asciidoctor implementation: https://github.com/elastic/docs?tab=readme-ov-file#callouts
Example: https://www.elastic.co/guide/en/observability/current/apm-open-telemetry-direct.html#apm-connect-open-telemetry-collector

@bmorelli25 bmorelli25 changed the title Support code callouts (needs issue) Support code callouts Dec 10, 2024
@bmorelli25 bmorelli25 added the authoring Relates to our markdown parser label Dec 10, 2024
@bmorelli25 bmorelli25 changed the title Support code callouts [Migration tooling] Code callouts Dec 17, 2024
@Mpdreamz
Copy link
Member

Mpdreamz commented Dec 18, 2024

I'm close to implementing this just a note on the syntax

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

@bmorelli25
Copy link
Member Author

This is fantastic! Syntax LGTM. Magic mode will be very nice for short-form callouts.

@Mpdreamz Mpdreamz linked a pull request Dec 19, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
authoring Relates to our markdown parser
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants