Add guide and update README to favor HTML documentation#3
Open
frntn wants to merge 2 commits into
Open
Conversation
Added a comprehensive guide on the advantages of using HTML over Markdown for documentation, including sections on information density, visual clarity, ease of sharing, and interaction capabilities.
Updated README to express preference for HTML over Markdown for better visualization and usability.
There was a problem hiding this comment.
Pull request overview
Adds a comprehensive README guide arguing for HTML as the preferred documentation/spec format (vs. Markdown) and describing practical use cases and example prompts.
Changes:
- Introduces a new README article: “Using Claude Code: The Unreasonable Effectiveness of HTML”.
- Adds rationale sections (information density, readability, sharing, interaction) and multiple use-case examples with linked screenshots.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Spatial data using absolute positions and canvases | ||
| - Images using image tags | ||
|
|
||
| I would go so far as to say that there is almost no set of information that Claude can read that you cannot fairly efficiently represent with HTML. This makes it a highly efficient way for the model to communicate in-depth information to you and for you to revie wit. |
|
|
||
| ### How to Get Started | ||
|
|
||
| I’m a little bit afraid that people will read this article and turn it into a /html skill or something. While there might be some value in that, I want to emphasize that you don’t need to do much to get Claude to do this. You can just ask it to “make a HTML file” or “make a HTML artifact”. |
| #### Example prompts: | ||
|
|
||
| - I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making. | ||
| - Create a thorough implementation plan in a HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest. |
|
|
||
| ### Code Review & Understanding | ||
|
|
||
| Code can be difficult to read in a Markdown file. But with HTML we can render diffs, annotations, flowcharts, modules, etc. Use this to understand code that the agent has written, to get code review or to explain a PR to someone reviewing your code. I find this often works better than the default Github diff view, and I attach a HTML code explainer to every PR I make now. |
|
|
||
| #### Example prompts: | ||
|
|
||
| - I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well. |
| I have honestly stopped using markdown altogether for almost everything, but I’m probably far on the HTML maximalist side of things. | ||
|
|
||
| How do I view the HTML file? | ||
| I tend just open it in a browser locally (you can ask Claude to open it), or upload to S3 if you want a shareable link. |
| This is honestly one of the biggest downsides of HTML, HTML diffs are noisy and hard to review compared to Markdown. | ||
|
|
||
| How do I get Claude to match my taste / not make it ugly? | ||
| The frontend design plugin helps Claude make good HTML files. But to match your own companies style, you can create a single design system HTML file by pointing Claude at your codebase. You can then use that design system file as a reference for other html files. |
| #### Example prompts: | ||
|
|
||
| - I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well. | ||
| - |
This file contains hidden or 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
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.
No description provided.