I'm writing a blog in ascidoc and would like the code listings to be automatically numbered, e.g.
Listing 1.3 The Hello World code
...
Listing 1.4 Some other code sample
Is there an attribute that I can set for the entire text so asciidoc would automatically number code listings?
It is not that clear in the asciidoctor user-manual (Listing Blocks), but in order for asciidoctor to number the listing you need to:
add a caption to each block
set the listing-caption attribute at the begining of your document
Example:
:listing-caption: Listing
.The Hello World code
----
//TODO: add hello world code
----
.Some other code sample
----
//TODO: Some other code sample
----
Controlling the way the listing blocks are numbered (1.1, 1.2 in your example) is not that easy. There is a discussion on GitHub for that.
Related
I am a beginner at asciidoc. I have structured my project into modular files so it is easier to manage. And I am able to generate the pdf using asciidoctor. However, the toc does not include the list of files it gets through the include directive.
Here is the main file:
= Booktitle
Vinay <email>
:sectnums:
:toc:
:toclevels:
:leveloffset: 1
include::chapters/chapter_00.adoc
include::chapters/chapter_01.adoc
include::chapters/chapter_02.adoc
:leveloffset: 0
Index
======
And here is chapter_01.adoc:
= The First Chapter
This is the first chapter.
The table of contents only includes a link to the Index. What am I doing wrong?
The command I used is: asciidoctor-pdf book.adoc
Your include is missing a pair of square brackets. For a book that has a title page, you might want to set the doctype attribute to book. The attribute toclevel should be set to a number indicating the heading levels you want to list in your table of contents. If you leave it empty, the table of contents will be empty.
Tested with Asciidoctor PDF 1.5.3 using Asciidoctor 2.0.10, the following worked for me:
= Booktitle
Vinay <email>
:sectnums:
:toc:
:toclevels: 2
:doctype: book
:leveloffset: 1
include::chapters/chapter_00.adoc[]
include::chapters/chapter_01.adoc[]
include::chapters/chapter_02.adoc[]
:leveloffset: 0
[Index]
= Index
Basically I want to write one piece of text which qualifies both as a working code and MarkDown (preferably GitHub flavor) for documentation. The language I'm using has C form commenting \\ for rest-of-line and /* ... */ for multi line comments. So far what I can do is:
/* --> start with multi line comments
here some markdown text
# heading
* list
end markdown section with
<!--- */ // -->
or
[//]: # (end of comment block --> */ // <-- inline comment)
_-_-indented code
_-_-_-_-more indented code
The issues are:
the first /* still showing in the documentation
I can't use the proper multiline code block ``` ... ```. I have to indent the code parts once more than what is required. Also the syntax highlighting doen't work in this format AFIK.
I would appreciate if you could help me know first how to solve above issues. and Secondly if there is any better way to do this?
I think I have a proper solution now with colapsible / foldable code section:
/*
This is the markdown **text**
used for documentation
<details>
<summary>Click to see the source code</summary>
``` scilab
*/
This is the
actual code
which will
be executed
/*
```
</details>
<!--- */ // -->
which will be rendered as:
/*
This is the markdown text
used for documentation
*/
This is the
actual code
which will
be executed
/*
The collapsible section makes sure that the documentation is clean and readable. you may see the final result here on GitHub. I used the code from here. Now there are a bunch of /*s and */s which would be nice to get ride of. Next step would be to modularize the MarkDown document into different files as I have asked here.
P.S. Implementation of the same idea using AsciiDoc here.
I am using python-pdfkit as follows to generate a PDF:
pdfkit.from_file(list_of_files, toc=toc, cover=cover, cover_first=True, options=default_options)
My problem is regarding the table of contents that is generated:
The table of contents is generated based on the H tags in the input
documents
If my html files are like:
index1.html
<h1>Title</h1>
...
[content]
index2.html
<h2>Subtitle</h2>
...
[content]
index3.html
<h3>Sub-subtitle</h3>
...
[content]
Since they are 3 different files, then the generated TOC is:
Title --------------------- Page x
Subtitle ------------------ Page y
Sub-subtitle -------------- Page z
Instead of
Title--------------------- Page x
Subtitle -------------- Page y
Sub-subtitle ------- Page z
I have tried merging all html files together but it is giving me a lot of problems with the internal links... linking to files instead to HTML #IDs gets tricky with a single HTML file all merged.
Any idea how to tell wkhtmltopdf to respect the H tags hierarchy without resetting it per file?
Thanks!
Edit:
After some discussion in the wkhtmltopdf github issues section, the only easy way of achieving this result is pre-parsing the HTML files to merge them all together.
See the following link for more details:https://github.com/wkhtmltopdf/wkhtmltopdf/issues/4310
I am making a series of design documents in Sphinx and I would like to include them together in a toctree and have the sections within the documents numbered. I know that I can use .. sectnum:: to number all sections in the child pages. However, Sphinx/rst numbers the title of the page (which is really just the first section) and the table of contents ends up looking like:
Table of Contents
1 Design the First
2 Design the Second
and each child page looks like:
1 Design the First
1.1 First Section
1.2 Second Section
What I want is a table of contents on my index page that just lists the title
Table of Contents
Design The First
Design the Second
and child page that look like
Design the First
1 First Section
2 Second Section
Is there a way to have a title that shows up in the TOC as well as on the top of a child page which does not end up being a numbered section?
I don't know what you ended up doing, but I wanted to do the exact same thing! I had the following setup:
index.rst
.. toctree::
assignment
library_api
I only wanted the assignment part to have numbers, so either could have done two separate toctree with one using :numbered:, or put at the top of the file
.. sectnum::
:start: 0
Giving of course the exact problem you mention -- my top-level title was Assignment Writeup, so that was 0 and everything below it in subsections was 0.x e.g.
Assignment Writeup
==================
First Task
----------
Second Task
-----------
gives
0. Assignment Writeup
0.1 First Task
0.2 Second Task
as it turns out, there's an easy hack you can do. It makes things more modular than probably desired, but "add a layer of indirection".
So now I have assignment.rst and assignment_writeup.rst. assignment.rst just basically has a title and a toctree:
Assignment Writeup
==================
.. toctree::
:maxdepth: 4
assignment_writeup
then take all sub-sections and put them in assignment_writeup and "upcast" their heading level. So I now take all subsections and make them sections, and subsub and make them sub.
.. sectnum::
:start: 0
First Task
==========
^^^ === instead of --- now
Second Task
===========
and we now finally have
Assignment Writeup
0. First Task
1. Second Task
kind of dubious, but this was the only way I could achieve it x0 I wonder what you did between asking this and now? Hopefully somebody will see this and benefit one day!
Note: this has undesireable side-effects. The Assignment Writeup shows up on its own page, with just Links to the indirect document. Not sure which is worse honestly...
Ho can I include inside an asciidoc code fence? Here is a sample:
[source,js]
----
function doit() {
*var thing;* // local variable
}
----
The idea is that I would like to highlight certain parts of the code block for teaching purposes.
The above sample doesn’t work.
I have read about using something like [subs="macro"], but (a) I can’t get it working in combination with a code fence, and (b) the documentation is a little unclear about the actual details.
Thanks
BTW I am aware of a similar question AsciiDoc add bold text inside a listing block, but there is no reference to code fences. I have tried the solutions, but the don’t work in this context.
According to AsciiDocs Documentation, below code
[source,java,subs="verbatim,quotes"]
----
System.out.println("Hello *bold* text").
----
will be displayed as
System.out.println("Hello bold text").
So, you need this -
[source,js,subs="verbatim,quotes"]
----
function doit() {
*_var thing;_* // local variable
}
----
It will be displayed as
verbatim and quotes subs are helpful.
NOTE:
One thing we need to keep in mind that the code block is already highlighting syntax. If you want different formatting, better not to use code block.
In my opinion the philosophy of Asciidoctor for those use case is to use callouts.
[source,js]
----
function doit() {
var thing; // <1>
}
----
<1> local variable
The second thing you should consider is to extract your code from a real, controled, unit-tested file. You define some markers in this code file and add an include directive in your adoc file.
Check slides 15-21 in this presentation:
Writing documentation with Asciidoctor