the default mapping is level 1(==) maps h2 in asciidoc
https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax
How to map level 1 to H1 when convert .adoc to .html?
I use an online markdown-like editor which use H1 as section title.
To achieve your goal, you would likely need to modify the converter.
Currently, the document title converts to H1. If a level 1 heading converts to H1, you'd have to figure out what the level 0 heading converts to.
You haven't stated your goal when making this change. However, if it is presentation-based, you can customize the CSS used to make an H2 look like an H1, continuing through the heading levels to making an H6 look like an H5.
Related
Looking into the official Asciidoctor documentation about Admonitions the addmonition look like:
The admonition is in the top left corner.
However, when I use the same admonition in my documentation the it looks like:
The admonition is on the left side of the text.
Are there some special Asciidoctor attributes I need to set in order to get the same look as in the official documentation?
The first example uses the CSS in the Antora UI, the second uses the standard Asciidoctor CSS. The HTML created in both scenarios is the same.
If you want the a similar styled HTML output as with the Antora UI, you'll need to borrow the necessary CSS from the Antora UI and integrate it into the theme you use for your HTML output.
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.
The a href links I create with CKeditor are part of h3 headings and appear smaller in font-size, from their counterpart non-link h3 text... For example, if the sentence is:
"We provide Google SEO support", and the word "Google" links to google.com, this word will appear smaller than the rest of that text (say 18px instead of 24px for the rest) and looks funny.
What can cause such a problem? what is worth checking in the text? Here is a link with a live example - You could see the problem in the second heading (h2) right away.
Thanks for you advice,
Provide CSS which format the elements as well as headings.Basically I think that your problem comes from assuming that if you format the header element in css it will affect the child elements too, it will not.
You can fix it like this:
h2, h2>a { font-size: 28px; }
This snippet causes all second headers and it's link children to have the same font size.
I would like to have several content blocks in my documents to output them in the templates at different positionions (eg aside and sections). In this case I do not want to work with partials. As I need some marginal jade formating, I can not put these into the Metadata as this is not rendered (as far as I tested it). Are there any other ways?
For illustration in the doc:
text1: p my first textblock
text2: h1 my second textblock
and in the template:
section document.text1
aside document.text2
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.