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

Feature/directives #1777

Merged
merged 93 commits into from
Feb 22, 2023
Merged

Feature/directives #1777

merged 93 commits into from
Feb 22, 2023

Conversation

facelessuser
Copy link
Owner

@facelessuser facelessuser commented Aug 6, 2022

Completely experimental. The idea is to (eventually) replace Admonitions, Details, and Tabs with a new directive format.
We won't be killing off replaced legacy extensions, not for some time.

Pros:

  • No indentation is needed.
  • Won't mess up your syntax highlighter in your code editor due to said indentation.
  • No more inventing new syntax for various new block features.
  • We can reuse this syntax for figure captures, embedding videos, etc. Opens the door for cool new features with minimal effort.
  • Any existing plugins converted to this format should have outputs that are compatible.
  • Would resolve features where people want to add IDs to tabs, Details, etc. We could expose these in the config for the given directive.

Cons:

  • New syntax to learn, but we won't be killing off legacy extensions right away.

What are we waiting on?

  • Needs feedback
  • Settle on what we call this extension (currently directives, but we could call them anything)
  • Settle on the final format/syntax.
  • Settle on the feature set/capabilities and API we provide.
  • Provide tests and ensure that there aren't any big corner cases we are missing.
  • Needs documentation

@facelessuser facelessuser added the S: work-in-progress A partial solution. More changes will be coming. label Aug 6, 2022
@gir-bot gir-bot added S: needs-review Needs to be reviewed and/or approved. C: docs Related to documentation. C: infrastructure Related to project infrastructure. C: source Related to source code. labels Aug 6, 2022
@facelessuser
Copy link
Owner Author

facelessuser commented Aug 6, 2022

I'll duplicate this here as well in order to get feedback:

Just an overall description of how the current prototype is laid out. I think I'm ready to discuss the syntax.

:::{directive-name} arguments
---
option1: value
option2: value
---

content
:::
  1. Fencing of blocks requires 3 or more :. If nesting blocks, the outer block should have a greater length of : than the child blocks. Currently, if a closing fence is encountered that is greater than or equal to the starting fence, it is sufficient to close the current fence.

  2. directive-name is currently the name of whatever directive you are using. It is case insensitive.

  3. arguments can be one or many arguments, and the given directive would specify required delimiters if required.

  4. The optional frontmatter containing options is YAML-ish bock that comes immediately after the header, or better put, is part of the header when specified. We currently went with YAML-ish to avoid pulling in PyYAML as a requirement. I'm kind of going with simpler is better right now.

    Due to limitations of the Python Markdown parser, it must be a "tight" config (no empty new lines). This also means there should be no newline after the initial header line.

    The key value pairs are similar to the meta extension (though I haven't yet made them multi-line, was considering this).

    The directive would impose any specific rules that these options require: delimiter split list, etc.

  5. content: any valid content can be used, even nested directives. There does not have to be a separation between the header and the content, but can be if desired.

Examples

Note with no content

:::{warning} All we need is a title!
:::
:::{warning} This is important!
Read this notice.
:::
:::{warning}
Arguments are optional with some directives!
:::
:::{figure} some/image.png
---
width: 300
---

I'm a figure caption, and you can specify optional settings for your directives as well!
:::
::::{tip} Here's a secret

:::{note}
You can nest directives as well
:::

::::

@gir-bot gir-bot added the C: details Related to the details extension. label Aug 6, 2022
@facelessuser
Copy link
Owner Author

facelessuser commented Aug 8, 2022

We could add the ability for these blocks to insert raw text. That is without an HTML wrapper. Why would we want to do this?

Well, IIRC, Python Markdown does not allow HTML except at the root indentation level. So under lists is impossible.

This should be pretty straightforward. If we mark a directive as being a text-only directive, we could simply store the content in the Python Markdown's stash and attach the placeholder to the end of the parent text or its last child's tail.

We could even add an event that allows you to process the text, such as formatting it for HTML, or just HTML escape it.

It's probably the only other case I can think of that people might want to do.

EDIT: I don't think we are going to bother with this right now. We don't want to blindly insert text.

@facelessuser
Copy link
Owner Author

The current syntax is what is up for debate. Do we keep the Myst like approach? Do we do something different? Under the hood, I think the functionality is all there.

@facelessuser
Copy link
Owner Author

Anyone checking this out should potentially voice their opinion syntax over at Python-Markdown/markdown#1175 as we've already got a good conversation going, but here is fine as well.

@gir-bot gir-bot added C: tabbed Related to the tabbed extension. C: tests Related to testing. labels Aug 23, 2022
@facelessuser facelessuser force-pushed the feature/directives branch 2 times, most recently from f99fd12 to 3ac9422 Compare August 27, 2022 13:06
@facelessuser
Copy link
Owner Author

Chunks are handed to parseChunk, but a chunk could have multiple blocks separated by \n\n. Maybe we should split these before calling on_add? This still won't catch cases where a block could be split automatically later:

Text
!!! note "Legacy admonition"
    content

We allow the same as above for generic blocks, but this would be at least two separate blocks.

Text
/// note | Legacy admonition

content
///

- Document missing config stuff.
- Document tracking data across blocks.
- Switch a number of parts over to generic blocks.
- Add custom generic block tool for collapsible code blocks.
@gir-bot gir-bot added the C: emoji Related to the emoji extension. label Feb 20, 2023
- HTML blocks use Emmet style tag and attribute defs
- Blocks no longer define `attributes` option, but instead use `$`
  and take Emmet style attribute defs.
- Admonitions and Details no longer define `type` attribute as it is
  redundant with using `$` to set a class.
@facelessuser facelessuser marked this pull request as ready for review February 22, 2023 16:16
@facelessuser
Copy link
Owner Author

@gir-bot lgtm

@gir-bot gir-bot added S: approved The pull request is ready to be merged. and removed S: work-in-progress A partial solution. More changes will be coming. S: needs-review Needs to be reviewed and/or approved. labels Feb 22, 2023
@facelessuser facelessuser merged commit 82d73d8 into main Feb 22, 2023
@facelessuser facelessuser deleted the feature/directives branch February 22, 2023 18:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C: details Related to the details extension. C: docs Related to documentation. C: emoji Related to the emoji extension. C: infrastructure Related to project infrastructure. C: source Related to source code. C: tabbed Related to the tabbed extension. C: tests Related to testing. S: approved The pull request is ready to be merged.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants