Replies: 322 comments 909 replies
-
|
How about Edit: Also, to add to this, maybe extend this behaviour to other parts such as headers in block quotes? I like to use headers because of their larger font size, but right now are they not included in this. |
Beta Was this translation helpful? Give feedback.
-
|
@dipree can you please update the summary to mention that |
Beta Was this translation helpful? Give feedback.
-
|
Just use a 2x1 table in wiki pages:
|
Beta Was this translation helpful? Give feedback.
-
|
Important @RahulVerma989 (https://github.com/orgs/community/discussions/16925#discussioncomment-7024899) Changelog indicates that you can change the tables to quoting with a header at wiki if you do not nest them. |
Beta Was this translation helpful? Give feedback.
-
|
Screenshots for @sinsukehlab - works at wiki:
|
Beta Was this translation helpful? Give feedback.
-
|
@krystian3w Yes, it also works at Wiki now. Update - 12 October 2023
|
Beta Was this translation helpful? Give feedback.
-
|
Thanks for this! Any way to customize the text? It would be very useful for non-English documents. |
Beta Was this translation helpful? Give feedback.
-
|
We should take into consideration that there are existing solutions outside of Github that already support the syntax that @laserlemon mentioned: Right now, Markdown files with this syntax are broken when viewed in Github. It would be great to see this custom text feature. Long awaited! 🎉 |
Beta Was this translation helpful? Give feedback.
-
|
I stumbled upon this discussion while looking for a way to customize the label. Because I regularly miss a Currently, I'm doing: Note Example: This is an example... But it's really not great. So, being able to do |
Beta Was this translation helpful? Give feedback.
-
|
I'm currently running into this issue in a repo. It would be really nice if the label was customisable. |
Beta Was this translation helpful? Give feedback.
-
|
Yes! I agree. It would be nice to have [!EXAMPLE] or it would be even better if I can use something like below! |
Beta Was this translation helpful? Give feedback.
-
Why not do this but with the commonmark syntax, and replace the emojis with simpler characters that look like them? :::i "Info" :::! "Warning" :::x "Danger" :::v "Affirmation" :::? "Tip" This way it's easily recognizable while not relying on english words. It looks like what it represents and it's easier to write than emojis. The syntax here is: |
Beta Was this translation helpful? Give feedback.
-
|
This is amazing 🔥 . This is now getting more features similar to AsciiDocs and AsciiDoctor 🎉 |
Beta Was this translation helpful? Give feedback.
-
|
great |
Beta Was this translation helpful? Give feedback.
-
|
Except that AsciiDoc has had native admonitions since forever (in the standard, not a GitHub-flavored AsciiDoc fork) but GitHub has never supported styling them at all. |
Beta Was this translation helpful? Give feedback.
-
Same with reStructuredText, it has extensive support for admonitions both specific and generic ( |
Beta Was this translation helpful? Give feedback.
-
|
It turns out you can use this new admonitions hack in reStructuredText as well by just using the 4-space block quote syntax. And you can even indent it using the #. List item
.. code:: bash
Do something
.. pull-quote::
**Warning**
**NB:** Something to be aware of
Still, I don't understand why GitHub still refuses to allow these with the built-in admonition directives in these languages. |
Beta Was this translation helpful? Give feedback.
-
|
Here is the issue for the broken rST rendering: github/markup#1682 |
Beta Was this translation helpful? Give feedback.
-
|
Would love to see more callouts too for different use-cases. These 5 below might be good to start with! I'm not sure if this is only for documentation, but I would use it in general issues and other places supporting markdown. I would especially like to see one that is red in terms of "caution". That might be especially useful with enforcing a code of conduct when you've already provided a warning and would be generally helpful with RFCs(request for comments) about any major signs of caution. |
Beta Was this translation helpful? Give feedback.
-
|
👍🏻 |
Beta Was this translation helpful? Give feedback.
-
@vassudanagunta AsciiDoctor supports locales for the admonition labels https://github.com/asciidoctor/asciidoctor/tree/main/data/locale as well as icons https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/#enable-admonition-icons |
Beta Was this translation helpful? Give feedback.
-
|
@toastal From your link it seems AsciiDoctor only supports icons in the HTML rendering, not in the source plain text. |
Beta Was this translation helpful? Give feedback.
-
I don't know that you’d want icons in your plaintext as it could be ambiguous at times. Also given how many open bugs there are for CLI tools to remove the emoji from the terminal (it really does look out of place), maybe plaintext is the place to keep emojis out. 🤷 But maybe it could work …and has the advantage of being (somewhat) language agnostic. Some symbols like stop signs are more universal. |
Beta Was this translation helpful? Give feedback.
-
|
AsciiDoc รองรับชื่อภาษาไทย แต่ต้อง compile ใน terminal |
Beta Was this translation helpful? Give feedback.
-
|
Clever backwards compatible syntax 👍 what about changing the colour of the block quote line to blue / yellow? if you wanted to go further, you could add a background colour as well that’s a lighter shade of the corresponding colour |
Beta Was this translation helpful? Give feedback.
-
|
😑 |
Beta Was this translation helpful? Give feedback.
-
|
You say “backwards-compatible syntax”; I say “spec-breaking & semantic-breaking syntax” |
Beta Was this translation helpful? Give feedback.
-
|
How about Check for checked information?
|
Beta Was this translation helpful? Give feedback.
-
|
use html text with css |
Beta Was this translation helpful? Give feedback.
-
|
Tags like Important, Checked, Issue would be very useful. Having a tag for all states of progress |
Beta Was this translation helpful? Give feedback.
-
|
ควย |
Beta Was this translation helpful? Give feedback.
-
|
ควยปั๊ก |
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
Why use the blockquote element? HTML Standard says:
|
Beta Was this translation helpful? Give feedback.
-
Agreed that the generated HTML should not use
But since we are defining new syntax, we get to define the semantics. We are specifically saying that I looked at the HTML GitHub is rendering it with, and they are not using a div+class as they should: <blockquote>
<p><span class="color-fg-attention"><svg>...</svg>Warning</span><br>
This is a warning</p>
</blockquote>This should be fixed. It not only violates HTML semantics, it's going to make it less accessible. I'm not an expert, but there is probably a proper ARIA way to do this. |
Beta Was this translation helpful? Give feedback.
-
|
I find the conversation around markdown grammar interesting and I think when you consider the design of the markdown syntax it backs up my point even more.
Firstly this violates the principle of least surprise - it's not totally clear why that renders a warning Secondly, how do I now quote someone that has actually said " And finally, the proposed syntax changes GithHub Flavored Markdown in such a way that it adds more context to the grammar. I believe this to be the root cause of the two symptoms above. |
Beta Was this translation helpful? Give feedback.
-
|
The idea of GitHub-flavored Markdown changing the semantics of a |
Beta Was this translation helpful? Give feedback.
-
Please do us a favour and don't shamelessly advertise your stuff nobody really has interest in. |
Beta Was this translation helpful? Give feedback.
-
|
Could use a pipe symbol ( |
Beta Was this translation helpful? Give feedback.
-
|
Hi, I like the idea but I would like to propose alternative syntax. GitHub Flavored Markdown is a superset of CommonMark and thus ideally it stays close to that if possible. The generic directives proposal for CM is already used in the ecosystem, take for instance This is how it would look: This would mean:
|
Beta Was this translation helpful? Give feedback.
-
|
GitHub just made a blog post about the |
Beta Was this translation helpful? Give feedback.
-
|
I also made a blog post. 👼 |
Beta Was this translation helpful? Give feedback.
-
|
We created a remark plugin to turn GitHub's syntax into the directive syntax: remark-github-admonitions-to-directives This helped us reuse markdown files in Docusaurus docs. |
Beta Was this translation helpful? Give feedback.
-
|
This syntax can be quite confusing, especially when writing in an IDE. |
Beta Was this translation helpful? Give feedback.
-
|
I think it is great to have the Githup callout syntax as proposed in the issue an now already available. And I also think that the two "callout" and "directives" are only in competition for admonition, not for custom directives. Why not support directives in addition too? 💪 As all static site generators like astro (starlight), docusaurus, vitepress, marp, sli.dev... are supporting directives, this would be a grate drop in feature :) IMHO I like directives more, as there is no @LuudJanssen great plugin for remark! |
Beta Was this translation helpful? Give feedback.
-
|
Nice feature! Any way to use without blockquote though? |
Beta Was this translation helpful? Give feedback.
-
|
There is, yes! |
Beta Was this translation helpful? Give feedback.
-
|
More customization is always nice. What if you could specify the Github's Octoicon, color, and text? For example: to render the alert octicon (https://primer.github.io/octicons/alert-16) with a hex color of
|
Beta Was this translation helpful? Give feedback.
-
|
As @pboling pointed out earlier, I would be wary of providing Markdown authors with syntax specifically to accommodate their Octicon symbol name as it may contribute to vendor lock-in. I do, though, wonder whether this feature is only expected to offer users a couple of options (the fundamentals) or whether we should be expecting more choices in the future? If we have one admonition for warnings, we should be given at least one more for the danger zone/error prone/high severity callout content as well. With the two current choices of |
Beta Was this translation helpful? Give feedback.
-
|
I don't think it is a good choice. But opening up a space for users to pick the best color would be better. Too rich colors can cause visual fatigue for users。 |
Beta Was this translation helpful? Give feedback.
-
|
Seems like... > **Note**
> Text...is currently rendered on the same line in readme files, instead of two separate lines like it does here in discussion comments: How it's rendered here:
How it's rendered in readme:
|
Beta Was this translation helpful? Give feedback.
-
|
Soft breaks are not part of GFM. They work in comments/issues/prs/releases, but not in readmes/gists. |
Beta Was this translation helpful? Give feedback.
-
|
Well, if GFM says that linebreaks are parsed as soft line breaks but GitHub does something different in issues/PRs, I'd then argue that issues/PRs are not GFM-compliant. The GFM spec (https://github.github.com/gfm/) is written by GitHub so they have every opportunity to clarify the situation but they don't, so in my eyes their rendering of comments/issues/PRs is just a different dialect of Markdown and not GFM, though it's close. (BTW I know this discussion is purely academic 😄.) |
Beta Was this translation helpful? Give feedback.
-
|
CM deals with parsing. GFM inherits that property. You could argue that GFM is not compliant to CM, because it adds onto it. |
Beta Was this translation helpful? Give feedback.
-
|
I have to admit that I'm not as sure about the technical details or even terms like you are, but in laymen terms, if comments/issues/PRs started rendering two trailing spaces ( But ok, it's the way it is, in the past I've spent quite some time browsing the "Writing on GitHub" section of their docs to find definitive answers but it's often quite fuzzy 🤷♂️. I'm not entirely confident in their implementation either, for example, this new "Note" / "Warning" feature has a lot of strange rendering bugs like |
Beta Was this translation helpful? Give feedback.
-
|
There isn't really a reason why markdown in issues, Pull requests and discussions can't be GFM. It's just a slightly modified one. And why it behaves so differently in terms of line breaks should be obvious here: Not everyone who files an issue or posts a discussion knows the ins and outs of Markdown, let alone GFM, so not having to deal with that two spaces thing for line-breaks makes it easier for those new people. We could argue about the semantics, backwards compatibility, etc. of GFM with CommonMark until the heat-death of the universe. In the end does it not matter here. When adding new stuff is GitHub most likely thinking about how it is the easiest and most convenient to use for the end-users, which may not always be programmers or people with vast CommonMark knowledge. I mean some other features of GFM are barely known such as that when writing a HEX colour inside an inline-code block, it renders a small icon in that colour: |
Beta Was this translation helpful? Give feedback.
-
|
Instead, why not use highlight syntax for Add an letter and an extra Normal quote: |
Beta Was this translation helpful? Give feedback.
-
|
Would be cool if this can share the same syntax as Microsoft Docs "alerts" and Obsidian's "callouts". MS Docs format [1]: > [!NOTE]
> This is a note.
Obsidian format [2]: > [!Note] Callout can have an _optional_ title
> Callouts can also be nested:
> > [!Hint]- You can also create foldable callouts with `+` or `-`
> > This is hidden until unfolded.
[1]: https://docs.microsoft.com/en-us/contribute/markdown-reference#alerts-note-tip-important-caution-warning |
Beta Was this translation helpful? Give feedback.
-
|
I had never heard of Obsidian before seeing it mentioned here. Other than Obsidian Publish, are other services using Obsidian-Flavored Markdown? I would be curious to know how portable the syntax is. |
Beta Was this translation helpful? Give feedback.
-
|
|
Beta Was this translation helpful? Give feedback.
-
|
Colors, more colores, yes |
Beta Was this translation helpful? Give feedback.
-
|
I agree to everything |
Beta Was this translation helpful? Give feedback.
-
|
I think this design format would make for a more readable and visible readme file. |
Beta Was this translation helpful? Give feedback.
-
|
This is awesome! 🚀 Would be great if we're offered more customization and standard syntax for these though. That'll allow many tools to auto support this.
|
Beta Was this translation helpful? Give feedback.
-
|
This syntax might hinder with what user actually wants to write The user will expect this to be rendered as following because
Also is Others have proposed great alternatives like Microsoft Docs Here is my take on the syntax. Suggestions are welcomed. |
Beta Was this translation helpful? Give feedback.
-
|
There is a Markdown RFC for a standard that would support this already. Not sure why they didn't use it, but it would be better to collaborate with the Markdown spec than make GFM even more of a monster. |
Beta Was this translation helpful? Give feedback.
-
|
i was thinking maybe |
Beta Was this translation helpful? Give feedback.
-
|
these are woking fine in github but when we create npm package and on package homepage it does not render as expected. how can we make shich support both places? here is one example of npm homepage |
Beta Was this translation helpful? Give feedback.
-
|
Stay away from this feature if you want your Markdown to work everywhere. There is no evidence that GitHub will be putting in effort to make this a community standard, nor does it seem they will continue improving it on their own platform. The list of bugs is long, and the list of external Markdown tools that don't support is always growing. |
Beta Was this translation helpful? Give feedback.
-
|
@pboling the problem is, npm is a subsidiary of GitHub. They should at least be consistent across their own platforms. |
Beta Was this translation helpful? Give feedback.
-
|
@csandman It is true that npm is now owned by GitHub, which is a subsidiary of Microsoft, but it was founded independently and then acquired by GitHub. They don't have to support the poison pill 'alerts' feature, while GitHub themselves can't implement it properly. |
Beta Was this translation helpful? Give feedback.
-
Sure they don't have to, I'm just saying they should be consistent. |
Beta Was this translation helpful? Give feedback.
-
|
Can the API (https://api.github.com/markdown) to convert Markdown to HTML be updated to include these admonitions? Currently, it ignores them and pretends it's regular text (e.g., |
Beta Was this translation helpful? Give feedback.
-
|
Stay away from this feature if you want your Markdown to work everywhere. There is no evidence that GitHub will be putting in effort to make this a community standard, nor does it seem they will continue improving it on their own platform. The list of bugs is long, and the list of external Markdown tools that don't support is always growing. |
Beta Was this translation helpful? Give feedback.
-
|
highlights are not working inside collapse
Note a note! |
Beta Was this translation helpful? Give feedback.
-
|
This is, unfortunately, intentional
It's been discussed multiple times above and has frustrated many people. Maybe Github will finally undo this change but I wouldn't get your hopes up. (linking for a record, no need to reply in every thread, don't spam) |
Beta Was this translation helpful? Give feedback.
-
|
It seems that customising the admonition title works only on VSCode:
But it does not work on GitHub: Preview here:
|
Beta Was this translation helpful? Give feedback.
-
|
I'm not sure which extension is rendering that, but if I were you, I'd be inclined to file a bug against it (assuming it's trying to be compatible w/ GitHub, which made it clear that this wasn't the way they intended the feature to work). |
Beta Was this translation helpful? Give feedback.
-
|
I'm not sure a big report is in order. They may be compatible with other markdown implementations that are actually officially specced. For instance, Obsidian among others. GitHub seems to be trying hard to avoid collaborating or creating something that can be portable. |
Beta Was this translation helpful? Give feedback.
-
|
Given this still isn't spec-ed, it's probably an opportune time to point out that the new Given it can appear at any nested heading level, I don't think - <div
+ <aside
class="markdown-alert markdown-alert-note" ...
>
- <p
+ <heading
class="markdown-alert-title" ...
>
<svg ... /> Note
- </p>
+ </heading>
...content paragraphs etc.
- </div>
+ </aside>Would be good to get input from people with more a11y/standards expertise though. |
Beta Was this translation helpful? Give feedback.
-
|
I brought the accessibility issues that had been highlighted previously (of which there were many few) to the attention of Github's internal a11y/standards accessibility team, highlighting the issues with it, and they disregarded our concerns, and gave it two thumbs up. It's a slap in the face to those of us who care. I posted screenshots elsewhere in this thread. Your analysis highlights more detail than I was able to, so perhaps that will assist them in doing their jobs, but I don't think they are inclined to listen to the community at all on this issue. This feature is intended to be ableist, english-speaker, candy only. The floor is obviously theirs to prove me wrong, and I hope they will. |
Beta Was this translation helpful? Give feedback.
-
|
may i request that user case choices are respected? all produce a word with it's first letter capitalised Warning like so internet convention associates volume intent with capitalisation. ie:
may we allow users to express volume intent by showing the note in the case chosen by the user? |
Beta Was this translation helpful? Give feedback.
-
|
IMO, this is what the levels themselves are for. Caution is a “louder” level than Warning. Important is louder than Note. I have not yet looked to see whether or not this behavior has been added to GitHub‘s fork of the Commonmark specification. But as an engineer who has to maintain a lot of software, I know that reducing entropy has a positive impact on software maintainability. Based on this, I would give this suggestion a thumbs-down. |
Beta Was this translation helpful? Give feedback.
-
|
@skyzyx The spec has last been updated in 2019, so it misses a lot of new features (Mermaid and math, for example). |
Beta Was this translation helpful? Give feedback.
-
|
That's really too bad. I think that there is a lot of value in ensuring that new extensions to Commonmark are well specified, so that we don't end up back in the same place we were before Commonmark existed. That was the whole point of the exercise. At the moment, GitHub does annotations one way, and other tools like Mkdocs does annotations a different way. Specifications matter. That was the number one problem with Gruber's original implementation in Perl — it was under-specified. |
Beta Was this translation helpful? Give feedback.
-
|
Yes, specs matter a ton, and that is why no one should be using this feature until GitHub decides they care about specs again. A 5 years dead specification that has clearly been abandoned is a loud signal, as is ignoring nearly all feedback in this "discussion". This feature is fundamentally broken, intentionally, and cannot be fixed, without completely ripping out the current implementation (CSS tricks) and properly adding admonitions to the parser spec. |
Beta Was this translation helpful? Give feedback.
-
OR |
Beta Was this translation helpful? Give feedback.
-
|
Doesn't this overlap with Info, Important or Tip pretty much all of the time? |
Beta Was this translation helpful? Give feedback.
-
|
I felt like notes, important info, and tips are usually short and are included with instructions to better assist with the overall understanding of the instructions. Example:
Important Be sure to install program as admin Note Install may appear to be frozen at times; this is normal. Tip For more features, download the extension. Caution Failure to install program correctly may result in fire. Warning If fire, you didn't run it as admin. |
Beta Was this translation helpful? Give feedback.
-
Yes, so the instructions would just be normal markdown content (headings, numbered lists, etc), covering a section or even the whole document. You don't need the instructions to be their own alert, because alerts are for emphasizing short spans of content to call special attention to them. If everything is emphasized, than nothing is emphasized. |
Beta Was this translation helpful? Give feedback.
-
In general I agree with you. But not absolutely. You can't assume that an author who chooses to have a tip with three short steps is overusing tips or other admonitions. It's not the place of a syntax to make such value judgements, at least not for a syntax like CommonMark, which is general purpose and not opinionated about content, only that markup should look natural to the reader. [🌶️ If I were designing an opinionated markup syntax for prose, I would limit headings to three levels, maybe even just two. See the section on Sections and Headings for Tufte CSS, particularly the note on the Feynman lectures. Both Edward Tufte and Richard Feynman are excellent communicators and writers.] I think "admonition" is a horrible choice of term. Notes, Tips, and Important messages are not the author admonishing you like a parent after you did something wrong. Even a warning is not an admonition. These are all interjections. [ℹ️ this is an |
Beta Was this translation helpful? Give feedback.
-
|
If @dipree or GitHub will add support for title overriding, all these custom cases are easily solvable with it: Maybe support can be added to replace the icon with emoji as well: (the note icon ℹ️ is replaced with 📝) |
Beta Was this translation helpful? Give feedback.
-
|
I like this feature, but unfortunately can't use it where I wanted to as it does not work when nested in bullet points. |
Beta Was this translation helpful? Give feedback.
-
|
However, it can't in Gist. I have tried it |
Beta Was this translation helpful? Give feedback.
-
|
Likewise in issues |
Beta Was this translation helpful? Give feedback.
-
|
It would be awesome to add highlighting for
The highlight would be red to draw the attention of contributors |
Beta Was this translation helpful? Give feedback.
-
|
Or we can customize as we wish. Set auto colors for default like: > ![NOTE]
>Example a note
> ![!WARNING]
> Example a warningand custom are assigned different colors. |
Beta Was this translation helpful? Give feedback.
-
It would be great to be able to customize, it would make the way of creating documentation via readme much more elegant |
Beta Was this translation helpful? Give feedback.
-
|
Admonitions are a lovely addition to GFM, thanks! It would be great if GitHub's ORG-syntax support could handle them directly as well, ala (e.g. in Note that pandoc supports org admonition blocks as of last February. |
Beta Was this translation helpful? Give feedback.
-
Just a small correction, Github did not add these admonitions to GFM nor have they created an official spec for them (like they should have and people have requested many times). They just added partial support for them in some locations around Github itself and indirectly forced every other MD parser to support them. |
Beta Was this translation helpful? Give feedback.
-
|
You're saying GitHub supported a partial version first before anyone else, and then other MD parsers started supporting a more feature-complete version, and now we're complaining that GitHub isn't feature-complete? |
Beta Was this translation helpful? Give feedback.
-
|
GitHub was very late to this feature with their terrible rendition. It has been discussed and worked on in other specs and parsers since 2013 at least. I suppose you could say they were the first to introduce the current worst ever version of admonitions for Markdown! We're complaining because this thread, and their bug-ridden feature implementation, is resulting in other tools and actual parsers being asked to implement this particularly horrible, not-even-official-GFM, version of admonitions. |
Beta Was this translation helpful? Give feedback.
-
|
fyi, comrak now supports these alerts. Works any place a normal block quote works. It also allows the title to be overridden, as well as supporting the GitLab multiline block quote syntax. So these work: |
Beta Was this translation helpful? Give feedback.
-
|
This will not be fixed. They did not implement this in the parser. This was intended as a "quick win" (@dipree 's words), and it was originally implemented with CSS tricks only. Additionally, it seems, based on changes to his GitHub profile, that @dipree is no longer working on this area of GitHub, and this broken beta feature appears to have been abandoned. This shortcoming has been pointed out since the very beginning of this thread, and GitHub has never taken it seriously, since it would be near impossibe to do with CSS tricks. |
Beta Was this translation helpful? Give feedback.
-
|
@pboling I don't see any CSS tricks. It's just plain HTML with SVG: 
Surely it should be simple for the Markdown parser to replace the |
Beta Was this translation helpful? Give feedback.
-
|
I updated my last comment to be more clear. It was originally implemented as CSS tricks. That was insufficient, so other tricks were added. In any case this was never added as a real feature to a real parser, and hopefully it never will be, for the many reasons spelled out in this extremely long thread. Your idea has been suggested countless times in this Discussion, and has never been given the slightest consideration by GitHub, except to say they can't do it, (see: CSS Tricks). GitHub would have to care (again) about Markdown before there is any movement on this. |
Beta Was this translation helpful? Give feedback.
-
|
I filed this entire feature as a bug in github-markdown: dipree/github-markdown#17 |
Beta Was this translation helpful? Give feedback.
-
|
@pboling That's @dipree's personal repository, and since he's no longer active on this, I doubt it will do any good. Thank you for trying though! |
Beta Was this translation helpful? Give feedback.
-
|
Does not support indentation:
You have to write:
Note 123
And visually is not know to what list the note is related. |
Beta Was this translation helpful? Give feedback.
-
|
I have same too, bug quotes and list: https://github.com/orgs/community/discussions/150331#discussioncomment-12027738 |
Beta Was this translation helpful? Give feedback.
-
|
This is, unfortunately, intentional
It's been discussed multiple times above and has frustrated many people. Maybe Github will finally undo this change but I wouldn't get your hopes up. (just linking for a record)
There's a really nice example page that shows the ways notes render (and don't render) for various situations including "nesting" example if you wanna see a more thorough example |
Beta Was this translation helpful? Give feedback.
-
|
I used to create my projects documentations with these alerts in order to have a cleaner visual with clear instructions. However, I just got back into doing it again and it's not working for me. I've checked above if someone has even given the mention of these not working and haven't found any. Am I missing something? Why aren't they working in github readme files? |
Beta Was this translation helpful? Give feedback.
-
|
The discussion is stupid long because GitHub has abandoned this feature, and people keep commenting about how it is broken ad nauseum, so you'll be forgiven for missing it, but the syntax for these admonitions changed, but the feature is still buggy, and won't be fixed, so I advise avoidance. |
Beta Was this translation helpful? Give feedback.
-
|
I see. Glad I asked then. Appreciate your attention on the question @pboling. Cheers |
Beta Was this translation helpful? Give feedback.
-
|
Perhaps this thread could be useful to educate on why English colonialism is problematic and worth tearing down.
Referenced sources are in the "References" section of the paper, and not reproduced here. If the so-called "accessibility (a11y)" team at GitHub needs access to the paper I can help them out. It is revolting that GitHub is proposing colonizing Markdown, a syntax composed of explicitly non-literary symbols, with hardcoded English terms, without support for any other language. EDIT: Originally I kept the line numbering of the source document in the quotations, but it is more readable to let the text flow naturally on the web, so now it does that. |
Beta Was this translation helpful? Give feedback.
-
|
Kindly fix your quotations btw. They look like this in mobile. (I will delete this comment once fixed. No need to reply.)
|
Beta Was this translation helpful? Give feedback.
-
|
You make a very fair point. Indeed if this feature is properly implemented, the use of syntax |
Beta Was this translation helpful? Give feedback.
-
|
Their main point is that if the feature was properly implemented, the syntax itself should not contain any English words like There are good ideas in this discussion, such as using triple-exclamation marks |
Beta Was this translation helpful? Give feedback.
-
|
I suppose that's also valid if Markdown doesn't already contain any control syntax based on English words. Most programming languages are based on English and can't be written in a different language. So for me, using English in syntax is normal. But I fully understand that Markdown is meant to be written with only symbols and no words in its syntax. We use |
Beta Was this translation helpful? Give feedback.
-
I think it should be noted that Markdown is not a programming language. It's a language for writing documentation. It's machine-readable, but also human-readable. We often think in terms of how Markdown gets rendered, but it is very readable in plain-text form. As such, I think language agnosticism is extra important, so you don't have to mix human languages.
As developers, it's easy to forget about non-developers sometimes. But part of why I like Markdown is that it's readable, even to people who don't know Markdown, and aren't familiar with markup languages. In the plain-text form So what's unfortunate to me is that I also find it unfortunate that it's sort of "overriding" the quote syntax. Using quotes to apply emphasis was a mistake from the very start IMO, and the fact that some GitHub users did that shouldn't have influenced this syntax's design IMO. Your suggestion about starting a line with |
Beta Was this translation helpful? Give feedback.
-
Alerts are an extension of Markdown used to emphasize critical information. On GitHub, they are displayed with distinctive colors and icons to indicate the importance of the content.
An example of all five types:
Here is how they are displayed:
Note
Highlights information that users should take into account, even when skimming.
Tip
Optional information to help a user be more successful.
Important
Crucial information necessary for users to succeed.
Warning
Critical content demanding immediate user attention due to potential risks.
Caution
Negative potential consequences of an action.
Update - 14 December 2023
Update - 14 November 2023
[!TIP]and[!CAUTION].**Note**isn't supported any longer.Update - 12 October 2023
Update - 28 July 2023
Thank you all once again for providing a ton of feedback. Few more changes based on that:
Update - 26 July 2023
Thanks for all the comments, we are working on a handful of fixes. One of them is to support soft line breaks in Markdown documents, so it will work the same in comments versus docs.
Update - 21 July 2023
We've made several improvements in response to your feedback:
divinstead of ablockquote.IMPORTANT.[!NOTE], has been added, which will gradually replace the old one. However, the old syntax will continue to work for some time.Thanks to all for your valuable input on this topic!
Initial - 10 May 2022
To better highlight and separate certain information from the rest in your documentation on GitHub, we now render a special and accessible note or warning blockquote in Markdown documents. We are using the existing syntax for blockquote and bold text.
This input:
Becomes:
Let us know what you think and how this helps you provide better documentation. Please note that this is a beta feature that might be subject to change.
Beta Was this translation helpful? Give feedback.
All reactions