-
-
Notifications
You must be signed in to change notification settings - Fork 2.8k
docs: use custom diff code blocks #5099
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Thanks for the PR, @Josh-Cena! typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community. The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately. Thanks again! 🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint. As a thank you, your profile/company logo will be added to our main README which receives thousands of unique visitors per day. |
✅ Deploy Preview for typescript-eslint ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this something we can build a docusaurus plugin for? To add the +/- in via css so the content is copyable?
I personally like diffs as it clearly shows what changes should be made which helps tell the story of how to configure things, IMO
We can, absolutely. but it would still mean showing two competing lines and when users copy, they have to delete the "-" line. Using highlighted lines makes it quite clear as well. |
I don't know what's going on with the Netlify preview, though—it's not showing the latest content😕 |
i do agree with that, if we want to make file copyable, maybe https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/website/src/css/prism.css .token.prefix {
user-select: none;
} |
Codecov Report
@@ Coverage Diff @@
## main #5099 +/- ##
==========================================
- Coverage 91.70% 91.32% -0.39%
==========================================
Files 362 132 -230
Lines 12181 1487 -10694
Branches 3530 224 -3306
==========================================
- Hits 11171 1358 -9813
+ Misses 661 65 -596
+ Partials 349 64 -285
Flags with carried forward coverage won't be shown. Click here to find out more. |
https://jsfiddle.net/fp2jrnmv/ [1] copying the above example yields:
Another option (or an additional option) could be to use JS to add a copy button which completely deletes the deleted lines from the copied contents. |
.language-diff .token-line > .prefix, /* you want to remove all prefixes, as non modifed lines have extra space */
.language-diff .token-line > .deleted, /* remove deleted elements */
.language-diff .token-line > .deleted + br { /* remove new line after deleted elements */
user-select: none;
} |
@armano2 - ah I missed the The result of the copy paste with armano's updated csshttps://jsfiddle.net/fmt0h31z/
This is exactly what we want - you can copy paste the true snipped AND we get to show the changes to tell a story. |
Great, I'll implement this and you can see the effect (hopefully—if the deploy preview updates) Also, what do we do about the copy button? Should we hide it entirely, or do you want it to have custom behavior as well? |
If it's not too difficult - having it do the same thing (copy the "intended" code) would be great! |
magicComments: [ | ||
{ | ||
className: 'theme-code-block-highlighted-line', | ||
line: 'highlight-next-line', | ||
block: { start: 'highlight-start', end: 'highlight-end' }, | ||
}, | ||
{ | ||
className: 'code-block-removed-line', | ||
line: 'Remove this line', | ||
block: { start: 'Removed lines start', end: 'Removed lines end' }, | ||
}, | ||
{ | ||
className: 'code-block-added-line', | ||
line: 'Add this line', | ||
block: { start: 'Added lines start', end: 'Added lines end' }, | ||
}, | ||
], |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
New Docusaurus feature to add custom metadata to lines—suits this use-case quite well.
I prefer using human-readable identifiers like "Remove this line", but if you want something that stands out more like for machines (e.g. "remove-next-line") just let me know
Ahhh... Customizing the copy button, even hiding it, is a bit hard at this stage. This would need some refactors in Docusaurus, but I'm not sure how. I hope the current solution is good enough. |
Current UI/UX is quite good IMO. We have syntax highlighting which is missed in diff code blocks. It's also more obvious that the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cross-posting from facebook/react-native-website#2984 — we'll probably consider making this the default behavior in Docusaurus. |
PR Checklist
Overview
The diff makes the code not directly copyable, which is not something you want for tutorial examples.
See related discussions at:
diff
codeblocks with line highlight facebook/docusaurus#4973