Don't execute certain blocks

[natew]

I just want to have some blocks be documenting how to use it, and then later define how it works.
So imagine that this would work (note the first blocks don't define a scripting language). Perhaps another thing like <!-- ignore --> would be better, so you can have it look like bash still.

run

Run npm in any apps/app folder, defaults to start. To run every app in dev mode for example just do:

maid run app
maid run desktop
maid run electron

which will end up running:

cd apps/app && npm run start
cd apps/desktop && npm run start
cd apps/electron && npm run start

But you can run any arbitrary npm command inside any package here too by using the fourth argument. So, maid run app build would run npm run build inside apps/app.

echo "hi"
cd apps/$1 || echo "not found" && exit 1
pwd

[zephraph]

I think this would be easy enough to do with something like

<!-- maid-ignore-start -->
```bash
maid run app
maid run desktop
maid run electron
```
<!-- maid-ignore-end -->

We could just take the processed markdown snippet and remove everything between those comments.

[natew]

Looks good but pretty verbose. Could we do a something that is easier to type?

[zephraph]

I suppose it'd be possible to just use <!-- maid-ignore --> and have that skip the next code block that it finds. That'd just be trickier to implement because it has to look ahead for the next code block and pull that out. Do you have any suggestions?

[natew]

Is there a way to have a bash pragma for the code block? Would mess up github I assume though. Like bash @ignore

[zephraph]

It seems to work...

echo test

```bash @ignore
echo test
```

I'm not sure if it'd have wider negative implications though.

[zephraph]

Actually, @natew, this might actually work now. bash @ignore won't be treated as a known type therefore shouldn't actually be ran... give it a try?

[tunnckoCore]

Don't think only for github. Those readmes are rendered in ton of places like NPM and such that rely on NPM registry to pull package readme.

maid-ignore-start and *-end may be a bit verbose but is the best, definitely.
Don't be soooooooo lazy 😆

[natew]

It’s not about laziness. The whole point is to make it easy to read as well when you’re editing. And to encourage people to write good documentation. Could be better solutions but laziness isn’t the motivating force here.

[tunnckoCore]

It's hidden to the consumers anyway. And it is enough good and explicit. Verbose things some times are good thing. And i'm always for explicitness. It might be even more confusing for some people when it only depend on just maid-ignore - what that ignores? only next? only next few? only next what? next few code blocks? and etc.

Pragma feels good too, but we are not sure where these files are rendered. Oh, one more place - yarn's package site.

[natew]

It’s very clear what it ignores. It’s less verbose, but not less clear in my opinion. If it works already then it seems like a great option for many. If you want to add a more verbose way, then I wouldn’t oppose. But this works for me better than the verbose one for this use case. For wanting to block off a big section I think the verbose one works too.

[chrisdmacrae]

Could this not be done with a custom code block identifier, specifically for commenting?

 ```maidcomment
  // code

[zephraph]

It could, but you'd break syntax highlighting.

[chrisdmacrae]

Totally valid point @zephraph. Just tested the @ignore syntax and it worked across the board. That's nicer.

[tunnckoCore]

We are not in javascript world and i don't understand why we should rely on pragmas or such, instead of just html comment as normally all will expect to work and it totally make sense to be that way.

Most markdown tools are using html comments - such example MarkdownLint? Not to mention that there's one more thing - Prettier for markdown may stop work? It works.

"Please be explicit" is my motto.

[zephraph]

The pragma works as is because it's no longer recognized as a runnable type. Technically you could put anything there that wasn't a supported type and it would be preserved. In this case, Github at the very least still syntax highlights. That means there's no changes needed to support doing

```bash @ignore
echo "Don't run this with maid"
```

I think it would be easy enough to add the html comment though.