MDN Document linting tools

MDN
#1

Hello everyone,

for those of you who haven’t seen this already, as part of GSOC we have been working on a set of tools to lint MDN documents to make the writer’s life easier and MDN docs more consistent.

This process has started at the beginning of June and we are ready to announce two things.

Doc Linter Webextension

We are ready to announce that we have successfully ported the SDK based add-on developped by Florian and Sebastian (https://github.com/Elchi3/mdn-doc-tests) to a working WebExtension (https://github.com/mdn/doc-linter-webextension).

This extension is adding a sidebar that you can open while editing a page on MDN and it can run a series of tests to let you know if there is any mistake in your page such as deprecated macros, too many links, empty elements, etc.

The WebExtension is a port from the SDK based add-on with nearly the same feature set as the add-on.

However, some features are not working yet due to API incompatibilities or other issues:

  • The sidebar doesn’t open automatically when editing pages: There is currently no API to open the sidebar programmatically.
  • There are no preferences implemented yet: This is due to the separation between the rules and the extension. This is making the modularity a bit more complex than expected.

The WebExtension should meet the requirements to be published on https://addons.mozilla.org and we’re planning to submit it soon.

Doc Linter Rules

We are also quite proud to announce that all the work that was put into making the rules used by the WebExtension also lead to making the rules available to other contexts as well, such as remote testing.

This has been done by a light refactoring of the existing rules to make them available as part of their own package (https://github.com/mdn/doc-linter-rules).

It opens a large set of possibilities such as testing directly in CKEditor, remotely, or before saving the document. The potential is great and we are thrilled to be able to make this available to everyone.

The WebExtension has already been modified to use this package of rules.

I did a very small Proof of Concept as an example of potential future remote testing (https://github.com/MatonAnthony/remote-mdn-linter).

What’s next ?!

A bright future for this project.

During the following month, we hope to solve as many bugs as possible and improve the package of rules.

We would also like to add features that you think are missing. If you would like a new feature or a new rule, feel free to open a bug in one of the repositories or to ping me (@anthony) or Florian (@fscholz) on IRC or send me an email.

3 Likes
#2

This is great news! Thanks a lot for your work on this, Anthony!

1 Like
#3

This is tremendously exciting! I’m checking this out right now to take a look! Having the ability to apply the linting from other tools is going to be particularly interesting to experiment with.

#4

Yeah, I could totally see adding a CKEditor plugin that integrates these rules to provide real-time feedback as you’re editing. It would not be difficult to do at all. I’m already looking at spending a solid chunk of Q3 doing editor enhancement work (with the blessing of the content team lead, Mr. Mills), and this might be something I can look into tackling once I get through some of the other stuff I’m already working on.

This is a very exciting notion, to me!

#5

Well done Anthony — this is really fabulous work.

#6

Yeah, I could totally see adding a CKEditor plugin that integrates these rules to provide real-time feedback as you’re editing. It would not be difficult to do at all. I’m already looking at spending a solid chunk of Q3 doing editor enhancement work (with the blessing of the content team lead, Mr. Mills), and this might be something I can look into tackling once I get through some of the other stuff I’m already working on.

This does indeed sound very interesting. We need ddn 55/56 bugs up to date, and I’d like you to make some regular contributions to the BCD repo to help with that, but apart from that I’d love you to spend time on CKEditor improvements.

#7

We have the immense pleasure to annnounce you that our Webextension has been approved by AMO and is now available at https://addons.mozilla.org/en-US/firefox/addon/mdn-documentation-linter

What does it change?

If you are using the old SDK based addon, you will get updated to the new extension. Sadly, the sidebar will also stop opening on its own when you edit a page as the API required for this does no longer exist and will not be developped in the future.

If you are not using the extension yet, you should totally consider it it’s great (disclaimer: I’m involved in the development :))

Changelog

I don’t have a full changelog to provide compared to the old addon as it’s our first release under the new architecture. But we have some interesting features.

  • Tests are now ordered by importance.
  • Tests can now also be run in “Source Mode” on CKEditor.
  • Some new test rules have been added.

What’s next?

The set of linting rules is living in its own repository and we would like to publish them as an npm package.

I am also experimenting with a server-side linting process using those rules that I expect to be able to showcase soon.

We would like to add missing features or rules, if you get any idea about a new potential rule or feature, feel free to open a bug in the corresponding repositories or to ping me (@anthony) or Florian (@fscholz) on IRC or to send me an email.

2 Likes
#8

:tada::tada::tada::tada::tada:
Looking forward to using this new version!

#9

This is great news, Anthony :smile: :tada:

#10

I have installed it and begun playing. Nice work!

#11

Is it possible to make this automatically open when in the editor but stay closed otherwise? Right now it seems a little unpredictable.

Sheppy

#12

I’m really sorry I forgot to answer you @sheppy.

Currently, it’s not possible as the necessary APIs are not available, they might be in the future but for now the necessary API is labeled as WONTFIX.

#13

We are happy to announce you the first patch for our WebExtension has been pushed to AMO to solve a few errors and bugs we encountered.

Changelog

  • We updated several dependencies (web-ext, eslint, fx-runner)
  • It is now possible to run the linter on multiple tabs without having to reload the page. (PR #48 Issues #44) (Thanks @sphinx_knight for testing that one)
  • A new rule testing that each internal links match a proper anchor has been enabled (PR #52 Tracking Issue #18)
  • The rule testing that each pre is having a proper class and that the class is not eval has been fixed to properly mark as ERROR the eval class and no longer flag children of the pre tag. (PR #52 Tracking Issue #35)

What’s next?

We still have the same goal as previously.

Call for opinions

We have a question for you, we are willing to add a keyboard shortcuts to open and close our panel but we don’t know which one would be suited, so we are looking for suggestions. If you have an idea feel free to post it in our dedicated github issue : Keyboard Shortcuts : Tracking Issue

If you have any questions or suggestions feel free to open an issue on github or contact me (@anthony) or Florian (@fscholz).

1 Like
#14

I love this add-on. I have a couple of suggestions I’m going to GitHub about right now. :slight_smile:
Sheppy