Asciidoc角色和gitbook

Question

I'm trying to use Gitbook with AsciiDoc (running Win10x64, NodeJS 6.9.1 and Gitbook v3.2.2) — I'm new to both of them.

The Gitbook documentation says AsciiDoc is supported since v2.0.0 and links to the AsciiDoctor documentation — I've checked the node packages, gitbook depends on gitbook-asciidoc which in turn depends on asciidoctor.js .

According to the documentation, AsciiDoc roles can be used to style both images and tables. They refer to classes that are applied to the HTML element, these classes being defined in the default AsciiDoctor sytlesheet.

But no matter how I try to apply a role, for example to an image (the [.text-center] shorthand or [role="text-center"] , I don't get the expected output (ie the image horizontally centered). The only way I can make it work for the image is by setting an attribute align="center", which is even not documented.

By inspecting the output in my browser I can see that classes are applied to the HTML elements but there's no matching CSS rules — the same goes for table styling as far as I've tried.

What am I missing here about the AsciiDoctor roles and stylesheets?

EDIT : asciidoctor.js is a devDependency of gitbook and is actually not installed with gitbook . The align="center" is documented in the AsciiDoc documentation but other features like table styling (at least the frame="none" and grid="none" ) don't seem to work with gitbook .

I still don't get why Gitbook documentation links back to the AsciiDoctor's one if it's not supported…

Answer 1

When you use AsciiDoc syntax in GitBook, AsciiDoctor is used to transform the AsciiDoc syntax into HTML. The HTML then uses GitBook CSS, because you're using a GitBook theme rather than an AsciiDoctor theme. That means that you don't get the default AsciiDoctor styling.

It's easy to add your own styles in GitBook. In your book.json , specify an additional stylesheet:

"styles": {
  "website": "styles/mystyles.css"
},

Then, create styles/mystyles.css so that it contains the CSS styles that you want to use:

.text-center {
  text-align: center;
}

You can copy styles from the AsciiDoctor stylesheet into styles/mystyles.css , but be prepared to tweak the styles and classes to work within the GitBook theme that you're using.