Publishing Asciidoctor.js packages to the @asciidoctor namespace

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

Publishing Asciidoctor.js packages to the @asciidoctor namespace

I'd like to start publishing Asciidoctor.js subpackages that originate from the Asciidoctor organization to the @asciidoctor namespace inside the npm registry ( I'll explain what the namespace is and why I think we should use it.

Until recently, the npm registry ( used a flat naming scheme. This meant that every package name had to be unique. The convention most projects adopt is to prefix the package with the name of the project (e.g., asciidoctor-docbook.js). This approach works fine for preventing naming conflicts. However, what it does not do is prevent anyone else from doing exactly the same thing. So what we end up with is packages that look like they're coming from the Asciidoctor organization, when in fact they are not. I don't want to suggest that these aren't good packages, but it does cause some confusion for users about which packages correlate to the Asciidoctor project (and we have little control over helping contributors name packages consistently).

That's where namespaces come in. Like the asciidoctor- prefix, a namespace provides a way to make package names unique (e.g., @asciidoctor/docbook-converter). However, the main difference (aside from a slight change in syntax), is that the namespace is also a group. That means we can control which packages can publish to it. That way, if someone sees a package that starts with @asciidoctor, they know it was published by the Asciidoctor project. They can also find a list of all packages at the URL

I'd also like to adopt the following naming convention for packages under the namespace:

package name: @asciidoctor/<variant>-<type>
repo name: asciidoctor/asciidoctor-<variant>-<type>.js

Here are some examples:

package name: @asciidoctor/docbook-converter
repo name: asciidoctor/asciidoctor-docbook-converter.js

package name: @asciidoctor/plantuml-extension
repo name: asciidoctor/asciidoctor-plantuml-extension.js

package name: @asciidoctor/cli
repo name: asciidoctor/asciidoctor-cli.js

The open question is what name to use for Asciidoctor.js itself. I think for that package we can still use asciidoctor.js (or just asciidoctor).

I've been using the namespace feature of the npm registry for Antora with great success. (See I think we should adopt it for Asciidoctor as well.


Dan Allen | @mojavelinux |