I'm using asciidoctor-pdf to create a PDF, and it is working nicely.
But when I use asciidoctor-epub3 to convert it to an epub it shows a warning message:
asciidoctor: WARNING: conversion missing in backend epub3 for toc
However, the toc is added in the generated epub and I cannot figure out why I'm seeing this warning.
This is the minimal .adoc file to reproduce the problem.
= Book title
:doctype: book
:toc: macro
toc::[]
Asciidoctor-epub3 added support for inline TOC in v 1.5.0, honoring the :toc: attribute.
If you use set :toc: attribute your epub will have an inline table of contents just after the cover/frontmatter page.
But, the support for custom placed TOC is still in progress. So, if you set :toc: macro and then use it with toc::[] to place your TOC in a custom location, it will be ignored and a warning message will be shown during compilation.
asciidoctor: WARNING: conversion missing in backend epub3 for toc
So, despite this warning your TOC is still placed in your epub but in a fixed position.
To avoid this warning you can wrap your toc code with a conditional:
= Book title
:doctype: book
:toc: macro
//...
ifdef::backend-pdf[]
// add custom placed toc only in pdf
toc::[]
endif::[]
Related
I have a .. toctree as part of a sphinx page, which includes relative links to other rst files in my package. How can I include a link to a subsection of a given page, rather than the full page itself?
I took a stab at
.. toctree::
page#section
But that didn't work. Any help is great.
After much hackery, I've come to the following solution, but I should first state that my goal was to:
have the heading NOT appear in the content body
have the heading appear in the TOC
So basically linking from the TOC to an arbitrary but invisible part of a document.
I needed this in order to be able to link to methods in some source code documentation rendered with Sphinxcontrib PHPDomain - these methods generate section links of their own, but do not get added into the TOC by default.
Step 1:
At the top of your RST file which needs this linking functionality, add a new role as such:
.. role:: hidden
:class: hidden
Step 2:
Somewhere in the content, use this role as such:
:hidden:`My Arbitrary Location`
"""""""""""""""""""""""""""""""
Step 3:
Add new CSS to the project (usually done by adding a CSS file into _static, or defining a style sheet or something like that - see this):
.rst-content .hidden {
display: none;
}
nav .hidden {
display: unset;
}
This forces the heading to be hidden in the content, but shown in the TOC.
Then, reuse the role as necessary in other documents.
Note that if your goal is to link to arbitrary locations in the document and still have the headings show up in the content, just change the CSS to style the headings to your liking rather than hide them.
When creating the ToC, Sphinx is including all headings and subheadings of referenced files within the configured tree depth. So you can simply not start the page with a heading and insert the heading at the point you want the ToC to point to, e.g.:
.. _my-rst-file:
**You can use bold print here if you want. This will not appear in the ToC**
.. rubric:: Or the "rubric" directive
And here some more text, normal font weight.
Here comes the heading that will appear in the ToC
""""""""""""""""""""""""""""""""""""""""""""""""""
And so on...
You need to include the page reference in the ToC as usual.
So in the ToC, you have:
.. toctree::
my_rst_file
In our example, the build result (HTML, PDF, whatever) will only have a reference to Here comes the heading that will appear in the ToCin the ToC.
I'd like to add a simple warning directive at the top of every page on a Sphinx RTD site:
.. attention::
The next major release of this project will launch on X date.
In the meantime, we're looking for feedback.
If you'd like an early preview, please reach out at someemail#someaddress.com!
What's the simplest way to do this? I'm using the sphinx_rtd_theme.
I can see how to add a block using the extrabody block, but it appears outside the main content area and is positioned and styled totally independently.
Ideally, I'd want this block to show up at an attention directive just below the breadcrumbs on every page.
You could add this to the conf.py Sphinx configuration file:
rst_prolog = """.. attention::
The next major release is imminent.
"""
and it will be included at the beginning of every source file that is read ‒ see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog.
F-string literals work too, so f'This is release #{release}' will substitute that variable value.
I'm generating PDFs via the rinohtype extension of Sphinx (i.e. not via the LaTex extension!).
For the two bundled rinohtype templates 'book' and 'article', where the latter is the one I use, the subtitle of the title page always starts with 'Release' by default (and a release version string if one is provided in conf.py via release = '1.0' - this is commented out in my case).
I want to:
1a) either get rid of the complete subtitle, i.e. also 'Release' isn't printed on the PDF title page, or
1b) want to change 'Release' to some other String, 'Rev.' in my case;
2) also have the modification of 1a) and/or 1b) applied to the page headers after "front matter", where 'Release' is also the default string.
What I found so far is:
Here it is described for LaTex, how to hide 'Release' (the subtitle) on the front page. However, this doesnt work for rinohtype. No real surprise, but I gave it a try because rinohtype also interprets some latex settings...
How do I get rid of the "Release 1" in the Page Header of the Sphinx Latex Output?
I also digged into rinohtype stylesheets and I found a way to hide elements of the title page. The linked stylesheet example shows how to hide the date entry on the title page. However, I'm not sure if this is actually the easiest solution (i.e. changing/extending the stylesheet) and this does also not hide the 'Release' String in the following page headers - see my Question 2) above.
https://github.com/brechtm/rinohtype/blob/40a63c4e5ad7550f62b6860f1812cb67cafb9dc7/tests_regression/sphinx_minimal.rts
rinohtype currently does not support changing "Release" into something else at the moment. This might be added in the near future however; see issue #157. This should also affect the page headers/footers.
You can hide the Release subtitle by means of a style sheet, like you discovered. It is also possible to remove it from the page header by supplying a custom template configuration. You'll need to override the header text for the contents and back matter page templates:
[contents_right_page]
header_text = '\t\t{DOCUMENT_TITLE}'
[contents_left_page]
header_text = '{DOCUMENT_TITLE}'
[back_matter_right_page]
header_text = '\t\t{DOCUMENT_TITLE}'
[back_matter_left_page]
header_text = '{DOCUMENT_TITLE}'
How to display a warning box in the html generated using the sphinx-build?
Warning
Do not use the directives sectnum, header and footer.
I want to show the above message as something like this:
(apologies, SO doesn't allow me to embed the image in the post here)
Please ignore the text formatting, my main aim to show a box with some text to get the attention of the user like on sphinx-doc site
The reStructuredText syntax you want is for things called admonition directives.
That specific example exists in the documentation source:
.. warning::
Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
:dudir:`footer`.
Is there a correct way to get Asciidoc to include headers and footers?
I am trying to work out whether Asciidoc is a serious contender for printed material. I know that it is supposed to be docbook compatible, but I can’t find out how to create chapters, headers and footers.
I am trying to create instructional material. Currently I am using Atom with the asciidoc plugin to create the text, and Marked 2 on the Mac to get a better look and to export it to PDF.
Running page headers and footers are not part of the AsciiDoc language but the tool you use for PDF conversion. From my view you have (at least) 2 options:
Follow the instructions in Exporting Print/PDF of your Marked 2 user manual to create page headers and footers (this might turn out difficult using the AsciiDoc processor instead of MultiMarkdown).
"You can specify headers and footers on a per-document basis using MultiMarkdown metadata at the very top of the document"
Since you probably have installed Asciidoctor anyway to support asciidoc in Marked 2 you could use an Asciidoctor PDF theme to generate PDF with headers/footers using Asciidoctor PDF. You would have to find an appropriate theme or create one yourself, though.
The most frequently used way to generate PDF output, however, seems to be generating DocBook output first and convert that to PDF using dblatex with DocBook XSL stylesheets (see AsciiDoc homepage). Maybe someone else can say more about that.