The MDN graph generates a summary of warnings by analyzing the build output of mdn/content. Some important caveats:
Below is individual documentation for each warning message.
This rule checks for internal anchor links that don’t point to an existing ID. The big benefit of analyzing build output is we can simultaneously avoid false-positives and false-negatives: it’s both aware of anchor links generated by macros and IDs generated by macros! See also mdn/mdn#561.
Some reports are easier to fix than others. You may either find the content on another page, on this page with another name, or nowhere at all, in which case you need to either remove the link or write the referenced content.
This rule checks for internal links that don’t point to an existing page. Note that broken macros don’t cause this rule to report, because broken macros are rendered without an href at all. Rather, they trigger the Flaw macros report.
Features in the Web Docs backlog are automatically exempted from reporting. The reports would be gone once the target page gets written. We also maintain a list of pages that could exist, which are also not reported in the aggregation. You should combine these three resources to determine what actions need to be taken.
For things that get reported, you should consider whether it refers to a page that should exist (in which case add it to no-page.txt and write the page some time in the future), or the link is invalid (in which case replace it).
This rule is the sidebar counterpart of broken link. Broken links generated by macros are reported by bad sidebar link.
[!NOTE] General remark about sidebar reports: we do a best-effort deduplication of sidebar content. That is, if multiple pages render the same sidebar, it’s only reported once for the first page that got checked.
This rule reports internal image links (ending in one of the image extensions). It’s generally a bad idea to provide links to them rather than directly displaying them and could be a typo. You don’t need to wrap images in another <a>.
This rule reports links to <dt>s where the <dt> contains a single link. You can usually replace such links with the actual <a> target, which is usually a page that offers more detail.
For example, you may have this on some page:
This property reflects the [`x`](/en-US/docs/Web/HTML/Element/foo#x) attribute.
And the <foo> page has this:
- [`x`](/en-US/docs/Web/HTML/Attribute/x)
- Description of `x`.
In this case, you can replace the link with:
This property reflects the [`x`](/en-US/docs/Web/HTML/Attribute/x) attribute.
Currently, this check only reports if the link to be replaced is a subpage of the original link. This ensures that if the DT links to a generic page like:
- [`x`](/en-US/docs/Web/HTML/Attributes_in_general)
- Description of `x`.
We don’t lose information by replacing it.
This rule reports links pointing to the page it’s already on, including links that contain an anchor but also the full path. Some of them are generated by macros.
[!WARNING] This rule is a best-effort, for-your-information report. It’s unlikely to false-negative (not report an actual broken link) but very likely to false-positive.
This rule extracts all external links and check whether they can be accessed. Unable to connect, timeout, invalid certificate would all cause this rule to report. The maximum timeout is 10s.
To fix the reports, go to the link and see if you can access it. If the site indeed cannot be accessed, remove the link or replace it with a valid one.
This rule reports jsfiddle.net/jsbin.com/codepen.io links. Internal examples using one of the MDN example repos or in-page using EmbedLiveSample are preferred. See mdn/content#16120.
This rule reports http: links. It would be mentioned if the https: equivalent is accessible. Most of the reports are unfixable because we don’t remove links just because they are not HTTPS, but it would be a good candidate to consider for removal.
This rule reports external links that are redirected to a different URL, including when the trailing slash is different. Replace the link with the redirected location.
Known link shorteners for bug URLs are exempted and are reported when not shortened by unshortened bug link.
This rule reports bug links where a known shortened version exists. For more information, see the BCD lint rule.
In an editor, you can do the following regex replacements:
| Find | Replace |
|---|---|
https?:\/\/bugzilla\.mozilla\.org\/show_bug\.cgi\?id=(\d+) |
https://bugzil.la/$1 |
https?:\/\/(issues\.chromium\.org)\/issues\/(\d+) |
https://crbug.com/$2 |
https?:\/\/(bugs\.chromium\.org\|code\.google\.com)\/p\/chromium\/issues\/detail\?id=(\d+) |
https://crbug.com/$2 |
https?:\/\/(bugs\.chromium\.org\|code\.google\.com)\/p\/((?!chromium)\w+)\/issues\/detail\?id=(\d+) |
https://crbug.com/$2/$3 |
https?:\/\/bugs\.webkit\.org\/show_bug\.cgi\?id=(\d+) |
https://webkit.org/b/$1 |
This rule checks for Markdown syntax that’s supposed to turn into a <dl> but is written incorrectly. We currently check two things:
<li> that starts with “: “.To fix this, check the source code. For example:
- Item1
- : Description1
- Item2
+ - : Description2
- Item1
- : Description1
- Item2
- : Description2
- - : Description3
+ Description3
This rule checks for <a> hrefs in content that’s not:
/en-US/#http link. Note that localhost URLs are also considered “bad”, unless they point to live samples (because Yari generates localhost URLs for local builds)mailto:, irc:, or news: link. We are considering whether they should be allowed but there are quite a few of these.Common cases include accidental relative links (foo instead of /en-US/docs/Web/.../foo).
This rule checks for <a> whose sole child is <code> whose text content contains a space. This is usually an error, such as using domxref to reference an API, but forgetting to remove code formatting (e.g. { {domxref("Fetch_API", "Fetch API")}}). Code formatting should only be used when indicating code entities, but linkable code rarely contains spaces (unless it’s demonstrating a function call, for example).
We have a wealth of exempted patterns and specific texts to filter out false positives. If false positives occur, consider adding them to check-content.ts (for generalizable patterns) or allowed-code-link-text.txt (for specific texts).
To fix these errors, the recommended way is to refactor it into a Markdown link ([Fetch API](/en-US/docs/Web/API/Fetch_API)), or, for the macros that support nocode-formatting, you can also pass the "nocode" parameter.
This is the underscore counterpart of code with space and could arise from usage of macros such as { {domxref("Fetch_API")}}. We also have exceptions encoded in check-content.ts and allowed-code-link-text.txt.
This rule reports multiple { {Specifications}} macros on the same page. This is generally a content bug.
This rule reports pages that has browser-compat keys in front matter but no { {Compat}} macros in content. Either remove the browser-compat key if it doesn’t exist in BCD, or add the table.
Yari does not generate flaws for { {CSSSyntax}} and { {CSSInfo}} that are missing data. See mdn/yari#8436 and mdn/yari#4487.
This rule reports pages without a sidebar. All pages should be associated with a sidebar.
This rule reports pages that has spec-urls or the browser-compat keys map to valid spec URLs, but has no { {Specifications}} macros in content. Add the macro.
This rule reports plain text that looks like Markdown. This can either be because the Markdown is nested within other HTML (usually tables), or because it’s using awkward text that must be escaped. The former should be replaced with the HTML equivalent and the latter should preferably be put into code spans.
This rule reports the style "`code`". This is an outdated convention and should be replaced with `"code"`.
This rule reports code spans that is immediately next to text that is not separated by whitespace. This rule is somewhat smart and:
<br> or another paragraph.code is not directly adjacent to the text, such as the structure <a><code>foo</code></a><em>bar</em>It also won’t report if the text is allowable punctuation, or common conventions such as foos, nth, etc.
The reports are either typos or poorly-formatted macros. Consider either adding a space for separation or changing the macro:
- `: block`
+
This rule reports the Yari bad_bcd_queries flaw. Fix reports by either adding BCD data, changing the query, or removing the compat table.
This rule reports the Yari broken_links flaw. Most of them are also caught by our warnings system, in which case broken link is emitted instead. Other times it reports self links, but its reports are not as complete because it doesn’t seem to report macro-generated links. This report is generally ignorable and other broken link warnings should be prioritized.
This rule reports the Yari macros flaw. This includes non-existent pages (which are not reported by broken link because broken xref macros do not contain href), incorrect macros (due to redirects), deprecated parameters, etc.
This rule is sort of a superset of unreachable via page. It reports pages whose parent page (page with the last segment removed) does not link to it. For example, you may add a method page but forget to link to it on the interface page.
This rule reports pages that are unreachable via any in-page links (starting from /en-US/docs/Web). All pages should preferably be accessible via some link but it could false-positive for some pages that are meant to be “tucked away”. You should consider whether it belongs to a feature group and should be linked from the landing page.
This rule reports pages that are unreachable via any sidebar. This is slightly trickier to fix until Yari fully exposes sidebar configuration to content; however, API sidebars are fully customizable.
This rule reports pages whose derived BCD keys are all missing in BCD. This should be fixed in BCD before a content fix.
This rule reports pages whose BCD keys don’t match the derived ones. This can be because of typos in the page slug or the BCD key, or because you should add or remove BCD keys. Note that the suggested keys may not all exist, but at least one of them is (otherwise not in BCD would be reported).
This rule reports pages whose page-type doesn’t match its location.
These are warnings that are unlikely to be fixable in content and therefore deprioritized.
This rule reports any link in the sidebar that either has no href or the href doesn’t start with /en-US/. It currently flags all links in the sidebar that are not internal links, and links generated by macros that point to nonexistent pages.
This is like broken anchor but is more likely a Yari bug. It checks for #browser_compatibility on pages without a browser compat section. This is nearly always because of the usage of the deprecated and experimental banners, which contain this anchor. This is unactionable.
This rule reports identical ids on the same page. Unless the content is hand-writing id, this is nearly always a Yari bug/limitation.