add an HTML formatter and converter tool #106
Conversation
QuietMisdreavus
requested review from
d-ronnqvist,
daniel-grumberg,
ethan-kusters and
franklinsch
|
@swift-ci Please test |
|
Alright, that finally sated CI. It turns out that i did not know the best way to restrict the JSON5 parsing to the right platforms! 😅 This also means that the implementation is a bit rough on non-Apple platforms, since i'd forgotten that you're required to quote property names in vanilla JSON. |
|
@swift-ci Please test |
|
This is amazing. Would you mind rebasing it so that we can begin to review and have it merged? |
|
@swift-ci Please test |
| /// A ``MarkupWalker`` that prints rendered HTML for a given ``Markup`` tree. | ||
| public struct HTMLFormatter: MarkupWalker { | ||
| /// The resulting HTML built up after printing. | ||
| public var result = "" |
There was a problem hiding this comment.
| public var result = "" | |
| public private(set) var result = "" |
| help: "Input file to print (default: standard input)", | ||
| completion: .file() | ||
| ) | ||
| var inputFilePath: String? |
There was a problem hiding this comment.
Nit. I see many CLI tool just use input to represent inputFilePath.
Actually, both is fine since most user will use a shorter
-iversion
| var inputFilePath: String? | |
| var input: String? |
There was a problem hiding this comment.
This is a positional argument so the caller does't write the argument name. However, a transformed version of this variable name does appear in the help text:
ARGUMENTS:
<input-file-path> Input file to print (default: standard input)
This is definitely nitpicking but maybe "" or something like that would be more informative in the help text.
There was a problem hiding this comment.
I don't think i can make it print an empty argument label, but i can at least rename the property to input or inputFile and reword the help text.
There was a problem hiding this comment.
Here's the result i just pushed:
ARGUMENTS:
<input-file> Markdown file to print (default: standard input)
There was a problem hiding this comment.
Sorry, I had written "<markdown-file>" but that got interpreted as an HTML tag and not displayed. I should have looked at the comment after I posted it.
|
@QuietMisdreavus : would you mind working in @Kyle-Ye 's change suggestions and rebase it? Thank you! |
| /// or else return an ``Aside`` with a ``Aside/Kind-swift.struct`` of ``Aside/Kind/note``, | ||
| /// this function will allow parsers to only parse an aside if there is a single-word aside | ||
| /// marker in the first line, and otherwise fall back to a plain ``BlockQuote``. | ||
| func isAside() -> Bool { |
There was a problem hiding this comment.
I feel like this API should be carefully considered. The existing Aside initializer is a bit more liberal with its parsing strategy in terms of the aside label, whereas i wanted to be more conservative in the HTML formatter. I think it might be more useful to introduce an optional initializer that allows for finer-grain selection of what counts as an aside label, so that you can optionally allow for multi-word labels, for example, or fall back to the existing permissive conversion where it will use a "Note" label if it doesn't parse one itself.
|
Will this been implemented? |
| help: "Input file to print (default: standard input)", | ||
| completion: .file() | ||
| ) | ||
| var inputFilePath: String? |
There was a problem hiding this comment.
This is a positional argument so the caller does't write the argument name. However, a transformed version of this variable name does appear in the help text:
ARGUMENTS:
<input-file-path> Input file to print (default: standard input)
This is definitely nitpicking but maybe "" or something like that would be more informative in the help text.
Co-Authored-By: David Rönnqvist <ronnqvist@apple.com>
|
@swift-ci Please test |
|
@swift-ci Please test |
|
It turns out the Swift-Foundation gained JSON5 parsing support in Swift 6.0, so i retooled the inline attribute parsing to enable support on non-Apple platforms when building with a Swift 6.0+ compiler. |
|
I'm going to merge this as-is for right now, and leave a couple action items for future enhancements:
While those enhancements could move this feature to become a highly customizable Markdown renderer, i believe that what we have here is already a great start. Please feel free to file enhancement requests if you start using this feature! |
|
I'm following this PR silently, great to see it merged. Thanks for the great work everyone! Do you plan to tag a release with the feature soon @QuietMisdreavus ? |
|
@lovetodream No. Swift-Markdown creates tagged releases based on Swift's release schedule, which means that this feature won't make it into a tagged release until the release after Swift 6.0. |
7 participants
Bug/issue #, if applicable: None
Summary
This PR provides an HTML renderer for the Swift-Markdown AST. This is extended from the base HTML renderer in swift-cmark due to two enhancements:
Asides instead, and emitting<aside>tags with an appropriate kind.^[formatted text](class: "fancy").The idea behind this is to enable Swift-Markdown to be used as a general-purpose Markdown renderer, a la
cmark-gfm. Future enhancements could involve parsing block directives to create custom block constructs, or other enhancements with inline attributes.Dependencies
None
Testing
As this is a general-purpose tool, testing is somewhat open-ended. As a proof of concept, you can check the output of rendering
Everything.md, in the tests directory:Steps:
swift run markdown-tool print-html Tests/MarkdownTests/Visitors/Everything.mdChecklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded (barring check-source)