bitovi / bitovi/documentjs

Tags that appear in code blocks get evaluated, escaped tags render weird

Open
#267 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
598
Forks
371
PR merge metrics
No merged PRs in 30d

Description

I was documenting a documentation process when I ran into this issue. I thought that a code block would change the behavior of DocumentJS. I also expected that escaping a tag would behave a certain way. Both situations have some issues. I'm listing both here because I'm not sure how best to solve the overall concern, which is how to escape a tag.

## Code Block Issue

When a tag appears in a code block, like `@package`, it should probably not be processed by documentjs engine.

If I have something like the following in a code block, for example, I would expect it to be skipped.

```md
@package
```

## Rendering an escaped tag

Attempting to escape a tag doesn't work as one would think either. Using `\@package` works in that the tag gets skipped but then the resulting documentation looks weird as the slash does not get removed.

## Escaping tag behaviors

**I think this issue should really just define these behaviors first.**

So, what should happen when...

- A tag appears in a code block
- A tag is escaped using `\`.
- (Am I missing any others?)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.