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 request] Support nested snippets by excluding all scissor lines from rendering #1980

Closed
ari-noumena opened this issue Mar 10, 2023 · 1 comment · Fixed by #2003
Closed
Labels
T: feature Feature.

Comments

@ari-noumena
Copy link

ari-noumena commented Mar 10, 2023

Description

When writing tutorials, a common use-case is to first show small parts of a file, before showing more extensive parts (or the entire file). For example:

// --8<-- [start:hello]
fun hello() {
	blah blah;

	// --8<-- [start:interesting]
	// Do some interesting stuff here!
	var x = foo();
	bar(x);
	// --8<-- [end:interesting]
}
// --8<-- [end:hello]

When hello is then included in some markdown, it will render a block like so:

fun hello() {
	blah blah;

	// --8<-- [start:interesting]
	// Do some interesting stuff here!
	var x = foo();
	bar(x);
	// --8<-- [end:interesting]
}

But the scissors aren't at all relevant to the example, and it's not desirable for the user to see them. It would be much nicer if they would see the following:

fun hello() {
	blah blah;

	// Do some interesting stuff here!
	var x = foo();
	bar(x);
}

One workaround is of course to duplicate the code (either in the same or different files, depending on how it works) such that there are no nested snippets, but that's a bit messy and makes it harder to maintain.

Benefits

It would benefit anyone wanting to render snippets containing nested snippets.

Solution Idea

If there are reasons for not wanting this behavior by default, perhaps it could be enabled as an option.

@ari-noumena ari-noumena added the T: feature Feature. label Mar 10, 2023
@gir-bot gir-bot added the S: triage Issue needs triage. label Mar 10, 2023
@facelessuser
Copy link
Owner

This seems like a reasonable request. I'll have to look and see if there are any complications, but I can't seem to think of any off the top of my head. I imagine we can do it as a post-processing step once the entire nested snippet is acquired. Just remove lines with the snippet syntax.

@facelessuser facelessuser removed the S: triage Issue needs triage. label Mar 10, 2023
StevenMaude added a commit to opensafely-core/ehrql that referenced this issue Sep 6, 2023
The snippet support in the PyMdown extensions removes nested snippet comments.

facelessuser/pymdown-extensions#1980

By wrapping the entire example dataset definition in a snippet section,
we can choose to include both sections and the entire file,
without having snippet comments in any of these.
StevenMaude added a commit to opensafely-core/ehrql that referenced this issue Sep 7, 2023
The snippet support in the PyMdown extensions removes nested snippet comments.

facelessuser/pymdown-extensions#1980

By wrapping the entire example dataset definition in a snippet section,
we can choose to include both sections and the entire file,
without having snippet comments in any of these.
StevenMaude added a commit to opensafely-core/ehrql that referenced this issue Sep 12, 2023
The snippet support in the PyMdown extensions removes nested snippet comments.

facelessuser/pymdown-extensions#1980

By wrapping the entire example dataset definition in a snippet section,
we can choose to include both sections and the entire file,
without having snippet comments in any of these.
StevenMaude added a commit to opensafely-core/ehrql that referenced this issue Sep 14, 2023
The snippet support in the PyMdown extensions removes nested snippet comments.

facelessuser/pymdown-extensions#1980

By wrapping the entire example dataset definition in a snippet section,
we can choose to include both sections and the entire file,
without having snippet comments in any of these.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
T: feature Feature.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants