Do not HTML-escape and use Markdown inline code for defaults #161
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
fmeum
force-pushed
the
code-escaping
branch
11 times, most recently
from
db8b8bb
to
b79d934
Compare
|
@tetromino Could you review this PR? I created it when I noticed that updating Stardoc from |
|
I agree with the PR in principle, but before reviewing and merging this, I want to move the markdown renderer java code here from the bazel repo and finally delete renderer_binary.jar instead of needing to keep updating it. Work is in progress, give me (and my reviewers) a few days. |
|
Sounds good! I updated the PR to point to Bazel master and will happily make further changes post-move. Just mention me. |
This reverts commit 3feb2a9.
Co-authored-by: Adam Azarchs <[email protected]>
|
@tetromino I rebased onto master including the move commit. |
tetromino
approved these changes
Jul 18, 2023
|
@tetromino Thanks! It would be great if this could be included in a release soon to unblock rulesets that need to update for repo mapping support. |
This release will break all existing golden markdown tests for Stardoc users. In order to minimize the frequency of such breakage, I want to additionally land the following breaking changes before cutting a release:
|
tetromino
added a commit
to tetromino/stardoc
that referenced
this pull request
Jul 25, 2023
… apply it properly Since bazelbuild#161 removed HTML escaping for defaults and function docstrings, we should do the same for attribute and param docs in table cells. The only limitations Markdown places on table cells are: * no pipe characters (they must be escaped with a backslash) * no newlines (they must be transformed into <br> or an HTML entity) The latter restriction makes it impossible to have a fenced code block inside a table cell. Therefore: * we do not escape HTML or Markdown markup outside a fenced code block * we keep existing logic for escaping newlines outside a fenced code block * we fix fence detection (e.g. allowing more than 3 fence characters to support embedded code blocks in code blocks, allowing tildes as fence characters, properly handling language names, etc.); * in code block content, we escape HTML, and we escape newlines as HTML entities (since <br> does not work in a <pre><code> block) - finally fixing code block newlines in table cells. This is a followup to bazelbuild#161.
tetromino
added a commit
to tetromino/stardoc
that referenced
this pull request
Jul 25, 2023
… apply it properly Since bazelbuild#161 removed HTML escaping for defaults and function docstrings, we should do the same for attribute and param docs in table cells. The only limitations Markdown places on table cells are: * no pipe characters (they must be escaped with a backslash) * no newlines (they must be transformed into <br> or an HTML entity) The latter restriction makes it impossible to have a fenced code block inside a table cell. Therefore: * we do not escape HTML or Markdown markup outside a fenced code block * we keep existing logic for escaping newlines outside a fenced code block * we fix fence detection (e.g. allowing more than 3 fence characters to support embedded code blocks in code blocks, allowing tildes as fence characters, properly handling language names, etc.); * in code block content, we escape HTML, and we escape newlines as HTML entities (since <br> does not work in a <pre><code> block) - finally fixing code block newlines in table cells. This is a followup to bazelbuild#161.
tetromino
added a commit
that referenced
this pull request
Aug 1, 2023
… apply it properly (#167) In Markdown table cells, apply HTML escaping only to code blocks, and apply it properly Since #161 removed HTML escaping for defaults and function docstrings, we should do the same for attribute and param docs in table cells. The only limitations Markdown places on table cells are: * no pipe characters (they must be escaped with a backslash) * no newlines (they must be transformed into `<br>` or an HTML entity) The latter restriction makes it impossible to have a fenced code block inside a table cell. Therefore: * we do not escape HTML or Markdown markup outside a fenced code block * we keep existing logic for escaping newlines outside a fenced code block * we fix fence detection (e.g. allowing more than 3 fence characters to support embedded code blocks in code blocks, allowing tildes as fence characters, properly handling language names, etc.); * in code block content, we escape HTML, and we escape newlines as HTML entities (since `<br>` does not work in a `<pre><code>` block) - finally fixing code block newlines in table cells. This is a followup to #161. Partially addresses #118
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Reverts #133 so that HTML escaping is not applied to Markdown. Instead, Markdown content such as docstrings can use HTML formatting and escape angle brackets with backslashes, HTML entities or inline code segments. Default values are embedded in inline code segments instead of
<code>tags, which does not require escaping.As a result, docstrings behave just like regular Markdown contexts while default values are rendered without smart quotes and can contain both
<and`without causing escaping issues.Also includes tests based on #138.
Fixes #137
Closes #138
Fixes #142
Closes #143
Requires bazelbuild/bazel#18867