owenh000 / asciidoctor-multipage Goto Github PK
View Code? Open in Web Editor NEWA configurable multipage HTML converter for Asciidoctor
Home Page: https://owenh.net/asciidoctor-multipage
License: MIT License
A configurable multipage HTML converter for Asciidoctor
Home Page: https://owenh.net/asciidoctor-multipage
License: MIT License
= Example Manual^Alpha^
Doc Writer <[email protected]>
2014-09-09
:icons: font
:source-highlighter: rouge
:rouge-style: monokai
:stylesdir: assets/styles/
:linkcss:
This is a user manual for an example project.
:sectnums:
[#introduction]
== Introduction
This project does something.
We just haven't decided what that is yet.
[#source-code]
[appendix]
== Source `Code` Example
[source,java]
.Java code from project
----
package com.diguage;
/**
* @author D瓜哥 · https://www.diguage.com/
*/
public class Main {
public static void main(String[] args)
System.out.println("Hello, world");
}
}
----
This page was built by the following command:
$ mvn
Gemfile
source 'https://rubygems.org'
gem 'asciidoctor', '2.0.11'
gem 'asciidoctor-multipage', '0.0.12 '
tmp.adoc
= h1
== h2
Build:
bundle exec asciidoctor -b multipage_html5 -D out/tmp -r asciidoctor-multipage tmp.adoc
Default outcome: out/tmp/tmp.html
contains a link to _h2.html
, which works fine in the local filesystem.
However, when pushing that output e.g. to GitHub pages, I would like the link instead to be just to _h2
instead of _h2.html
.
Both _h2
and _h2.html
work on that server, but the .html
one is just uglier.
Maybe we can have a:
-a html_ext=0
to remove it.
If a document contains a table with a multi line cell (with prefix a), the table of contents is generated into this cell.
Example document with html output attached.
tested with version 0.0.15
command used to create html output:
docker run --rm --user
I was hoping to disable stylesheets across all pages output by asciidoctor-multipage using stylesheet!
(as documented here) but only the first page has stylesheets removed.
I'm able to use --no-header-footer
to remove stylesheets but this actually removes more than I intend (the entire header section). Is this an issue that would be addressable in asciidoctor-multipage?
cc @ajitredhat
When using the [appendix]
annotation, the numeration (A, B, C, ...) of the chapters shown in the table of contents seems to be wrong.
Below is a simple example that has two top-level appendix chapters with two subsections each. The result produced by asciidoctor-multipage book.adoc
(version 0.0.15 using asciidoctor version 2.0.17) is shown in the screenshot below: The top-level chapters of the appendix are incorrectly named C and D in the table of contents, but are correctly named A and B in the document itself. The subsections however are named correctly in both places. When testing the same input with the standard single-page html5
converter it produced the expected result, so I hope my input is right.
= Appendix-Test
:doctype: book
:lang: en
:toc: left
:toclevels: 2
:numbered:
[appendix]
== First Chapter
=== First Section
=== Second Section
[appendix]
== Second Chapter
=== First Section
=== Second Section
Run asciidoctor using --out-file to set de output filename:
$ asciidoctor -r asciidoctor-multipage -b multipage_html5 --out-file out/index.html src/main.adoc
Then out/index.html is created, but the links to home in every file refer to main.html, so all are broken.
I know the option -D works fine, but to be able to set the filename of the top-level document, allows to save it as index.html, for example, ready to publish the directory in a website.
After some research, I guess docname is used as the node ID of top-level document and the link URL for home derive from that ID.
Could it be solved if outfile (maybe, without extension) is used instead? I don't know if that change could break other things.
When compiling this minimal example:
= Sample Document
Author Name
:doctype: article
:toc: center
:sectnums:
== Level 2
Some text goes here
=== Level 3
other text goes here
with the command asciidoctor -r asciidoctor-multipage -b multipage_html5 -D out sample.adoc --trace
I get the following output:
Traceback (most recent call last):
20: from /usr/local/bin/asciidoctor:23:in `<main>'
19: from /usr/local/bin/asciidoctor:23:in `load'
18: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/bin/asciidoctor:15:in `<top (required)>'
17: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/cli/invoker.rb:113:in `invoke!'
16: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/cli/invoker.rb:113:in `each'
15: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/cli/invoker.rb:130:in `block in invoke!'
14: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/convert.rb:189:in `convert_file'
13: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/convert.rb:189:in `open'
12: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/convert.rb:189:in `block in convert_file'
11: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/convert.rb:117:in `convert'
10: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/document.rb:936:in `convert'
9: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/converter/html5.rb:84:in `convert'
8: from /home/palle/.gem/ruby/2.7.0/gems/asciidoctor-multipage-0.0.3/lib/asciidoctor-multipage.rb:190:in `convert_document'
7: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/document.rb:936:in `convert'
6: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/converter/html5.rb:84:in `convert'
5: from /home/palle/.gem/ruby/2.7.0/gems/asciidoctor-multipage-0.0.3/lib/asciidoctor-multipage.rb:124:in `convert_document'
4: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/converter/html5.rb:218:in `convert_document'
3: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/converter/html5.rb:88:in `convert'
2: from /var/lib/gems/2.7.0/gems/asciidoctor-2.0.12/lib/asciidoctor/converter.rb:389:in `convert'
1: from /home/palle/.gem/ruby/2.7.0/gems/asciidoctor-multipage-0.0.3/lib/asciidoctor-multipage.rb:393:in `convert_outline'
/home/palle/.gem/ruby/2.7.0/gems/asciidoctor-multipage-0.0.3/lib/asciidoctor-multipage.rb:247:in `generate_outline': undefined method `level' for nil:NilClass (NoMethodError)
If I remove the line :toc: center
I don't get any error, but the link from sample.html
to Level 2 as an incorrect href: <a href="#_level_2">Level 2</a>
. This should rather be <a href="_level_2.html">Level 2</a>
I'm using the following gem versions:
asciidoctor (2.0.12, 2.0.10)
asciidoctor-multipage (0.0.3)
Gemfile
source 'https://rubygems.org'
gem 'asciidoctor', '2.0.11'
gem 'asciidoctor-multipage', '0.0.12 '
tmp.adoc
= h1
== h2
Builds fine with the standard:
bundle exec asciidoctor -b multipage_html5 -D out/tmp -r asciidoctor-multipage tmp.adoc
Outcome: out/tmp/tmp.html
and out/tmp/_h2.html
are generated as expected.
But if I add --template-dir template_dir
on the command line to create custom output elements (see https://stackoverflow.com/questions/63917971/how-to-create-custom-html-output-for-an-existing-asciidoctor-asciidoc-macro/63917972#63917972 ):
mkdir template_dir
bundle exec asciidoctor -b multipage_html5 -D out/tmp --template-dir template_dir -r asciidoctor-multipage tmp.adoc
then only out/tmp/tmp.html
is generated, but not out/tmp/_h2.html
.
It does not make a difference it template_dir
contain anything or not.
The project is a great extension.
I want to use it to publish my documents. So I tried the extension. I found a problem: source highlight style does not extract to a file; the style of asciidoc is extracted to a file.
Unfortunately it is possible to put a section header inside a table cell with the "a" operator. The asciidoctor-multipage extension may not handle these sections as expected.
I hope section headers are seldom, if ever, being used inside table cells. Thus, fixing this issue is ultra-low priority. If however you want to see this fixed then this is the issue for you to comment on and/or work on.
Hi,
Jekyll has a plugin for asciidoctor that allows an easy way for static website generation https://github.com/asciidoctor/jekyll-asciidoc. Is there a plan to add multipage extension support to it to leverage the chunking capabilities?
Thanks!
I have custom roles in my headers, something like
== [.breadcrumb]##InternalTest.##[.api-function]##getHelloWorld()
The corresponding <span>
elements are generated but they seem to be escaped in the TOC because I get this in the output:
<li><a href="API_Crown_InternalTest.html#API_Function_InternalTest.getHelloWorld"><span class="breadcrumb">InternalTest.</span><span class="api-function">getHelloWorld()</span></a>
</li>
Can't do a sed hack, there absolutely no difference in the child list from a regular list: https://github.com/************/china-************/blob/e7e9032f11734012f837c9003c39d085fa8afd31/push#L25
At gem 'asciidoctor-multipage', '0.0.12'
It feels to me a bit too hard to separate the header body from he list of children that goes at the bottom.
This is especially true if the header ends in a large Asciidoctor list for example:
= h1
* one
* big
* list
== h2
== h3
it would be hard for readers to see that the list in h1
ends at list
and that h2
and h3
that follow are the children as it renders something like:
* one
* big
* list
* h2
* h3
I would recommend adding a marker for that, e.g. saying Table of Contents or Children in bold. e.g. like:
* one
* big
== Table of contents
* h2
* h3
Sample live rendered example: https://************.com/china-************/anti-ccp-info-sources.html that illustrates the difficulty.
Here's an example of the output style I went for on my own markup language: http://************.com/evil#toc
Hi, thank you for creating this project!
I have a question regarding cross-references. When you generate the document into multiple pages, it no longer seems to be possible to refer to IDs in different files. Consider the following:
[#section-a]
== Section A
...
Please refer to section <<section-a>>.
When generating just one document ($ asciidoctor main.adoc
), pressing on the hyperlink correctly directs you to the defined section. When you generate that document into multiple pages with your plugin, it no longer works. Ideally it should direct you to the other document.
Do note that I define the main.adoc
like this:
include::chapter_a.doc[]
include::chapter_b.adoc[]
Is this feature supported? Thanks.
After installing this with gem install asciidoctor-multipage
, the program has 0640 permissions, so cannot be read by non-root users:
ls -l /usr/lib/ruby/gems/2.7.0/gems/asciidoctor-multipage-0.0.5/lib/asciidoctor-multipage.rb
-rw-r----- 1 root root 20427 Feb 26 11:32 /usr/lib/ruby/gems/2.7.0/gems/asciidoctor-multipage-0.0.5/lib/asciidoctor-multipage.rb
This seems to result from the permissions inside data.tar.gz in the Gemfile:
tar ztvf data.tar.gz
-rw-r----- wheel/wheel 20427 2021-02-05 07:28 lib/asciidoctor-multipage.rb
I think this is probably inherited from the build environment, but I don't know Ruby or GitHub runners enough to be sure.
Here's the error, in case it helps someone find the issue:
/usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:92:in `require': cannot load such file -- asciidoctor-multipage (LoadError)
I see inconsistent behavior when using the extension with or without a pagebreak ('<<<<') included in the preamble. It appears that attributes set in a file that is included prior to the pagebreak are not being set, or perhaps are being scoped out of existence by the time those attributes are used in the following document markup. I haven't tried to further characterize if anything else might not work, but do have a trivial test case which I'll attach. The prebuilt outputs are included and just 'make compare' will show the differences. 'make clean compare' will regenerate the outputs. Building without the extensions and with the normal 'html5' target generates identical outputs with the attributes properly set (I haven't included a rule for this, as the differences in behavior of the extension WRT the page break are the issue).
This is using asciidoctor-multipage 0.0.12, asciidoctor 2.0.12, and Ruby 2.5 on Debian stretch.
Consider for example an h6.
The default Asciidoctor style for h6 is tiny, even less visible than a regular paragraph, and compared to the toplevel h1, it is barely visible.
So if I direct a reader to a h6, it is hard for them to understand what that page is about immediately, because the output looks like:
the-h6-this-page-is-about.html
= Toplevel h1
====== The h6 this page is about
where Toplevel h1
is huge, and renders before, while The h6 this page is about
is tiny and just below.
The h6 this page is about should be rendered much larger I believe. In particular, h1-h6 should all be the same size on the split.
The extension needs to have some parts rewritten. Specifically, a separate Page class, unique to this extension, needs to be added to represent each separate Page in the resulting output, rather than having this extension's code spread around extending the other stock Asciidoctor classes.
This should simplify the code significantly, making it easier to understand, and will make it much easier to resolve open issues (even resolve some of them without any work on them specifically).
This issue needs to be completed before most of the other open issues can be worked on.
There is automatically a footer element added with something like:
Version 0.1
Last updated 2021-06-14 16:23:50 +0200
Is there a way of customizing/removing just this part? I tried adding this at the top of my main .adoc file (see documentation):
:docinfo: shared-footer
And while my custom footer specified in "docinfo-footer.html" was then added at the very bottom of the page, the original footer was still there right above it.
On a possibly related note, I found that the package adds this
<style>.toc-current{font-weight: bold;} .toc-root{font-family: "Open Sans","DejaVu Sans",sans-serif;
font-size: 0.9em;} #content{display: flex; flex-direction: column; flex: 1 1 auto;}
.nav-footer{text-align: center; margin-top: auto;}
.nav-footer > p > a {white-space: nowrap;}</style>
after it includes the contents from my originally specified css file (also: not quite sure why it copies all that instead of just linking to it but ok). What is a bit annoying here is that it specifies the font-family
for .toc-root
and while I had specified a different font everywhere in my normal css file, this was always overwriting the settings for this individual element, which means it didn't fit to the rest of my style anymore. Maybe this could instead inherit from something else?
Hey there,
are there any plans to get this working with newer Asciidoctor versions?
I have tried to do it myself but I am not familiar with the Asciidoctor code base and so far I've come up empty.
Thanks.
Given is an Asciidoc source file foo.adoc
. If translated with asciidoctor-multipage using the command-line argument -o
, the passed output file name is ignored in the ToC:
$ asciidoctor-multipage -a webfonts! -D /tmp/foo/ -o index.html foo.adoc
The first page of the multi-page output is named index.html
. However, the link in the ToC points to foo.html
.
Link to first page in ToC points to index.html
.
The problem can be reproduced, adding :partsnum:
to the preamble of the test document basic-multipart.adoc
:
= Basic Multipart Test
:doctype: book
:toc: left
:partnums:
and running the tests afterwards:
$ bundler exec rake test
...
1) Error:
AsciidoctorMultipageTest#test_black_box_docs:
NoMethodError: undefined method `divmod' for "I":String
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/helpers.rb:262:in `block in int_to_roman'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/helpers.rb:261:in `each'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/helpers.rb:261:in `map'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/helpers.rb:261:in `int_to_roman'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:98:in `sectnum'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:500:in `convert_section'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/converter/html5.rb:55:in `convert'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/abstract_block.rb:75:in `convert'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:513:in `block in convert_section'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:510:in `delete_if'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:510:in `convert_section'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/converter/html5.rb:55:in `convert'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/abstract_block.rb:75:in `convert'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:223:in `block in convert_document'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:220:in `delete_if'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:220:in `convert_document'
/..../asciidoctor-multipage/lib/asciidoctor-multipage.rb:252:in `convert_embedded'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/converter/html5.rb:63:in `convert'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/document.rb:948:in `convert'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/convert.rb:118:in `convert'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/convert.rb:190:in `block in convert_file'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/convert.rb:190:in `open'
/..../asciidoctor-multipage/vendor/bundle/ruby/2.7.0/gems/asciidoctor-2.0.16/lib/asciidoctor/convert.rb:190:in `convert_file'
/..../asciidoctor-multipage/test/test_asciidoctor-multipage.rb:16:in `block in test_black_box_docs'
/..../asciidoctor-multipage/test/test_asciidoctor-multipage.rb:10:in `foreach'
/..../asciidoctor-multipage/test/test_asciidoctor-multipage.rb:10:in `test_black_box_docs'
...
I think the error is caused by lib/asciidoctor-multipage.rb#L98 because @Numeral already is in roman numbers when sectnum() method is called in part sections.
I fixed it, changing the line to:
%(#{@numeral}#{append})
Now all test pass.
With these files:
index.adoc
= Pirate Product Documentation
:toc:
:leveloffset: +1
include::index2.adoc[]
:leveloffset: -1
index2.adoc
= Pirate Backend
:leveloffset: +1
include::Configuration.adoc[]
:leveloffset: -1
Configuration.adoc
= Pirate Configuration Reference
== Value Specification
[cols=","]
|===
|abc.$\{ext} a|
* item
|===
Multipage, when invoked as:
$ asciidoctor -a multipage-level=2 --trace -v -r asciidoctor-multipage -r asciidoctor-diagram -b multipage_html5 -D. -o index.html index.adoc
throws an NPE:
Traceback (most recent call last):
23: from /usr/bin/asciidoctor:23:in<main>' 22: from /usr/bin/asciidoctor:23:in
load'
21: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/bin/asciidoctor:15:in<top (required)>' 20: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/cli/invoker.rb:113:in
invoke!'
19: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/cli/invoker.rb:113:ineach' 18: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/cli/invoker.rb:130:in
block in invoke!'
17: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/convert.rb:189:inconvert_file' 16: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/convert.rb:189:in
open'
15: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/convert.rb:189:inblock in convert_file' 14: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/convert.rb:123:in
convert'
13: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/document.rb:971:inwrite' 12: from /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:541:in
write'
11: from /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:541:ineach' 10: from /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:544:in
block in write'
9: from /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:544:inopen' 8: from /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:545:in
block (2 levels) in write'
7: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/document.rb:944:inconvert' 6: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/converter/html5.rb:84:in
convert'
5: from /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:126:inconvert_document' 4: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/converter/html5.rb:218:in
convert_document'
3: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/converter/html5.rb:88:inconvert' 2: from /home/vps/.gem/ruby/gems/asciidoctor-2.0.15/lib/asciidoctor/converter.rb:389:in
convert'
1: from /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:408:inconvert_outline' /home/vps/.gem/ruby/gems/asciidoctor-multipage-0.0.9/lib/asciidoctor-multipage.rb:252:in
generate_outline': undefined method `level' for nil:NilClass (NoMethodError)
$ asciidoctor -v
Asciidoctor 2.0.15 [https://asciidoctor.org]
Runtime Environment (ruby 2.7.3p183 (2021-04-05 revision 6847ee089d) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
I'm testing the asciidoctor-multipage
extension and want to generate asciidoctor HTML multipages. I'm also interested in PDF and one-page HTML.
I made the following test documents attached here ["test.adoc", "chap1.adoc", "chap2.adoc", "chap3.adoc"]
.
= Title: Subtitle
:author: Sam
:email: [email protected]
:description: asciidoctor-multipage
:keywords: Asciidoctor, Multipage
:doctype: book
:backend: docbook
:stem: latexmath
:figure-caption: Figure
:figure-number:
:source-highlighter: highlight.js
:numbered:
:eqnums: Equation
:imagesdir: images
:sectnums:
This document contains all 3 chapters.
include::chap1.adoc[]
include::chap2.adoc[]
include::chap3.adoc[]
***
== Chapter 1
This is my chapter one.
[stem#eqn-normalStress,reftext='{eqnums} {counter:eqnum}']
++++
\begin{align}
\sigma\ (\text{stress}) = \frac{F\ (\text{load})}{A\ (\text{area})}\ \frac{N}{m^2}
\end{align}
++++
From <<#eqn-normalStress>>, you can calculate the normal stress.
== Chapter 2
This is a test chapter 2.
[stem#eqn-normalStrain,reftext='{eqnums} {counter:eqnum}']
++++
\begin{align}
\epsilon\ (\text{strain}) = \frac{\Delta L\ (\text{change in length})}{L\ (\text{original length})}
\end{align}
++++
From <<#eqn-normalStrain>>, you can calculate strain.
== Chapter 3
This is the final test chapter.
[stem#eqn-twistShear,reftext='{eqnums} {counter:eqnum}']
++++
\begin{align}
\text{Shear strain, } \gamma = \frac{R\theta}{L}
\end{align}
++++
Calculate shear strain from <<#eqn-twistShear>>.
Having installed the required extension packages on Ubuntu 20.04, I used the following commands to generate the outputs in various directories.
$ asciidoctor --backend html5 -D htmlDir -a data-uri test.adoc
$ asciidoctor -r asciidoctor-multipage -D htmlsDir --backend multipage_html5 -a data-uri test.adoc
$ asciidoctor -r asciidoctor-pdf -r asciidoctor-mathematical -D pdfDir -b pdf test.adoc
All documents are generated successfully, except that, unlike in the PDF and the one-page HTML output, the asciidoctor-multipage
HTMLs output seems to reset or forget the latex equation counter on every page. Every equation is labelled (1) even when the cross-reference correctly indicates Equation 3.
I would like asciidoctor-multipage
to remember the counter and match all equation labels as in (1) (2) (3) on various pages. Not (1) (1) (1). How do I force the asciidoctor-multipage
extension to preserve the latex equation numbering similar to the PDF and the one-page HTML?
Thank you.
Regards, Sam.
HI,
I have followed the instructions I have found in the Asciidoctor discussions regarding the Ruby installation: https://discuss.asciidoctor.org/Using-the-multi-page-converter-from-maven-tt8549.html#a8550 as I had the same origin problem as the author.
but now I get the following error:
Failed to execute goal de.saumya.mojo:gem-maven-plugin:2.0.1:initialize (install-gems) on project docs-public: Execution install-gems of goal de.saumya.mojo:gem-maven-plugin:2.0.1:initialize failed: Java returned: 1
do you have any idea what is causing the problem?
Thanks in advance.
asciidoctor-multipage adds this
<style>.toc-current{font-weight: bold;} .toc-root{font-family: "Open Sans","DejaVu Sans",sans-serif;
font-size: 0.9em;} #content{display: flex; flex-direction: column; flex: 1 1 auto;}
.nav-footer{text-align: center; margin-top: auto;}
.nav-footer > p > a {white-space: nowrap;}</style>
after it includes the contents from the originally specified css file. What is a bit annoying here is that it specifies the font-family
for .toc-root
and while I had specified a different font everywhere in my normal css file, this was always overwriting the settings for this individual element, which means it didn't fit to the rest of my style anymore. Maybe this could instead inherit from something else?
after:
apt install ruby-rubygems
gem install asciidoctor-multipage
run as user:
ubuntu@u2:~$ asciidoctor-multipage
/usr/local/bin/asciidoctor-multipage:25:in load': cannot load such file -- /var/lib/gems/3.0.0/gems/asciidoctor-multipage-0.0.16/bin/asciidoctor-multipage (LoadError) from /usr/local/bin/asciidoctor-multipage:25:in
errors.
/var/lib/gems/3.0.0/gems/asciidoctor-multipage-0.0.16/bin/asciidoctor-multipage is installed with: -rwxr-x--x permissions.
chmod +r /var/lib/gems/3.0.0/gems/asciidoctor-multipage-0.0.16/bin/asciidoctor-multipage
fixes the problem.
A feature suggestion:
When opening a page, locate the content on that page and display the content link of this page on the screen.
If a document content is very long, open a later page, and the content link of this page is not displayed on the screen.
I converted a document of type book that contains variables in headings, for which a TOC (aligned left) included unresolved data:
:var-label: FooBar
[#foobar]
=== {var-label}
The section heading is rendered in the TOC as {var-label}
whereas it appears to be correctly substituted with FooBar
within the actual content.
The test file is
:product: Wibble
:toc: left
:numbered
= User guide
== Getting started with {product}
X
== Details
Y
After conversion The right hand pane (content) is correctly
but the left hand pane (TOC) is
Downloaded version today (28 Feb)
Asciidoctor 2.0.12
The example:
= Example Manual^Alpha^
Doc Writer <[email protected]>
2014-09-09
:icons: font
:source-highlighter: rouge
:rouge-style: monokai
:stylesdir: assets/styles/
:linkcss:
This is a user manual for an example project.
[#introduction]
== Introduction
This project does something.
We just haven't decided what that is yet.
[#source-code]
== Source `Code` Example
[source,java]
.Java code from project
----
package com.diguage;
/**
* @author D瓜哥 · https://www.diguage.com/
*/
public class Main {
public static void main(String[] args)
System.out.println("Hello, world");
}
}
----
This page was built by the following command:
$ mvn
The command:
$ asciidoctor-multipage -v
Asciidoctor Multipage 0.0.16 using Asciidoctor 2.0.17 [https://asciidoctor.org]
Runtime Environment (ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-darwin19]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
$ asciidoctor -r asciidoctor-multipage -b multipage_html5 -D . -a toc=left index.adoc
The generated HTML:
<p>↑ Up: <a href="a.html">Example Manual<sup>Alpha</sup</a>> | Next: <a href="source-code.html">Source <code>Code</code> Example</a> →</p>
Hello! I'm a new user to asciidoctor and asciidoctor-multipage so please bare with me 😅 . I have a main.adoc
where I'm including some attributes use throughout. For example:
= My page
include::data/shared-metadata.adoc[]
{metadata_0}
== Page 1
{metadata_1}
== Page 2
{metadata_2}
data/shared-metadata.adoc
contains the attributes referenced.
When I build the adoc normally, they are rendered as expected. However, when I build using asciidoctor-multipage, The resulting output only shows attributes on the main page (metadata_0
) but pages 1 and 2 only show the place holders.
asciidoctor -r ~/code/asciidoctor-multipage/lib/asciidoctor-multipage.rb -b multipage_html5 main.adoc -D out
Is it possible for the included adoc to be inherited and render those attributes in other HTML pages?
No matter what i set multipage-level
to I always get a document that looks like this:
I want to Split the document into pages for the second level sections (the ===
sections). Here's the source:
= Sample Document
Author Name
:doctype: book
:toc: center
:toclevels: 3
:multipage-level: 3
:sectnums:
= Part 1
Intro
== Level 2
Some text goes here
=== Level 3
other text goes here
== Other Level 2
Some more text goes here
=== Level 3
additional text goes here
Built using the following command: asciidoctor -r asciidoctor-multipage -b multipage_html5 -D out sample.adoc
Am I doing something wrong?
I'm using the following gem versions:
asciidoctor (2.0.12, 2.0.10)
asciidoctor-multipage (0.0.3)
The example:
= Example Manual
Doc Writer <[email protected]>
2014-09-09
:icons: font
:source-highlighter: rouge
:rouge-style: monokai
:stylesdir: assets/styles/
:linkcss:
This is a user manual for an example project.
[#introduction]
== Introduction
This project does something.
We just haven't decided what that is yet.
[#source-code]
== Source Code
[source,java]
.Java code from project
----
package com.diguage;
/**
* @author D瓜哥 · https://www.diguage.com/
*/
public class Main {
public static void main(String[] args)
System.out.println("Hello, world");
}
}
----
This page was built by the following command:
$ mvn
The highlighter options are :source-highlighter: rouge
and :rouge-style: monokai
. But the generated style file is rouge-github.css
.
If I use monokai
, the generated style file is rouge-github.css
. But the source-code.html
links to rouge-monokai.css
.
$ asciidoctor-multipage -v
Asciidoctor Multipage 0.0.16 using Asciidoctor 2.0.17 [https://asciidoctor.org]
Runtime Environment (ruby 3.0.0p0 (2020-12-25 revision 95aff21468) [x86_64-darwin19]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
$ asciidoctor -r asciidoctor-multipage -b multipage_html5 -D . -a toc=left index.adoc
$ tree .
.
├── assets
│ └── styles
│ ├── asciidoctor.css
│ └── rouge-github.css
├── index.adoc
├── index.html
├── introduction.html
└── source-code.html
It genereated the <link rel="stylesheet" href="assets/styles/rouge-monokai.css">
, but did not generate the style file:
The segemnt of source-code.html
:
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<link rel="stylesheet" href="assets/styles/asciidoctor.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="stylesheet" href="assets/styles/rouge-monokai.css">
rouge-monokai.css
should be generated. It is not rouge-github.css
.
On the one hand I think it's really neat that the TOC is collapsed/expanded as needed, however, it would be even better if the default collapsed state could be customized. Alternatively, the default TOC representaion should be the same as the value for :multipage-level:
, i.e., such that each of the individual pages can be seen and clicked in the TOC directly. For example, right now with :multipage-level: 2
it takes me two clicks to reach a specific section page, since I can only click the chapter in the TOC and then need to wait until it expanded to find the section.
Asciidoctor supports block-level content in table cells with the AsciiDoc "a" attribute. See the Asciidoctor User Manual. It doesn't seem like a good idea, but it allows the writer to put things like lists and other such things in a single table cell.
It looks like Asciidoctor internally processes this type of cell as as a separate document. The multipage extension currently breaks when it encounters this new document.
Hey, I've been using asciidoctor-multipage for several years now, for several projects, the biggest of which is http://docs.olivetin.app ( https://github.com/OliveTin/docs.olivetin.app ), and as a developer myself I know that I appreciate when people say thank you, so, thank you! ;-) asciidoctor-multipage has made my life writing longer documentation much easier than having to use something like asciibinder.
I'm not sure if this is a support request (because I've not found the configuration option yet), or a feature-request (if this isn't yet possible), but I'd like the page title to be reflected in the html - currently every page uses the document title, ie;
= OliveTin
:title: OliveTin documentation
:multipage-level: 2
[#installation]
== Installation guide
blah
Which renders: <title>OliveTin documentation</title>
on installation.html. I would much rather something like; <title>Installation • OliveTin Documentation</title>
but just <title>Installation</title>
would be good enough.
The reason being is that it helps people with lots of docs tabs open (often that is me), and helps differentiate search engine results. eg, this isn't great;
Footnotes should be supported. Footnotes should be shown at the bottom of the respective pages.
A test suite needs to be added for automatically testing the extension and validating the HTML output (both standalone and embed-able). The sample document in test/
could be used as a starting point.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.