From all examples I can find, Asciidoc's footnote is written inline:
http://www.seinan-gu.ac.jp/~shito/asciidoctor/html_chunk/chap73.html
The first time you enter a footnote you want to reuse, give it a unique ID in the first position.
The next time you reference the footnote you only need to insert the ID in the square brackets
Though it allows referencing footnote by id, but the example only references inline footnote.
How to write a footnote elsewhere, and reference in the main body of text? My footnotes can sometimes be a few paragraphs, so inline makes less sense.
Currently, there is no facility to control footnote positioning. See: https://asciidoctor.org/docs/user-manual/#user-footnotes
If you can live without auto-numbering, you can simulate footnotes using standard Asciidoctor notation:
== A section
A bold statement<<myfootnote1,^[1]^>>
== Another section
== Footnotes
[horizontal]
[[myfootnote1]]^1^::
Express your opinion in a brave way.
Related
I have Sphinx documentation containing math blocks via the math directive. By default, they are centered in the HTML output. I want them all to appear aligned at the left, but with some indentation with respect to the surrounding text.
For example, if this is in index.rst
For :math:`|r| < 1`:
.. math::
\sum\limits_{k=0}^{\infty} r^k = \frac{1}{1-r}
Text in following paragraph put here to demonstrate that the math block
is in fact centered on the page.
and conf.py is completely empty, then running sphinx-build . output in the same folder produces the following HTML page as viewed in the browser:
I want that formula and all other math blocks left-aligned with something like 2 "em" indentation. This question asks how to left-align a single math block. I'm hoping there is a way to achieve the same effect throughout the documentation without changing each and every math directive in the reStructuredText source.
This answer applies to MathJax, the default mathematics renderer in HTML output.
The following setting in conf.py left-aligns all math directive content:
mathjax3_config = {'chtml': {'displayAlign': 'left'}}
Indentation can be customized with displayIndent:
mathjax3_config = {'chtml': {'displayAlign': 'left',
'displayIndent': '2em'}}
References:
https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax3_config
https://docs.mathjax.org/en/v3.0-latest/options/output/index.html#options-common-to-all-output-processors
I need a way to escape from Sphinx’s limitation that HTML output contains one and only one page per level-1 heading. For the sake of readability, some of my document’s content must be divided into pages at a lower heading level.
I’m considering whether I can do this by manipulating the table of contents in the left sidebar, as follows.
Suppose I have a document with this structure:
Little section
A subsection
Another subsection
Big section
Level 2 in a big section
Another level 2 in a big section
Another little section
Normally the document would have three pages beginning with the headings “Little section,” “Big section,” and “Another little section.” But I want two additional pages, beginning with the headings “Level 2 in a big section” and “Level 2 in another big section.” I would do this as follows.
Put each level-2 section in a separate reST file, which makes its initial heading a level-1 heading from Sphinx’s point of view.
Add the :orphan: option to each “level 2” reST file so that it doesn’t appear in the sidebar TOC automatically.
Manually add level-2 entries to the sidebar TOC under “Big section” which have the text “Level 2 in a big section” and “Another level 2 in a big section,” and link to the orphaned “level 2” files.
I’m asking whether this is possible because I saw the following statement on sphinx-doc.org Directives page. I have put the relevant part in italics:
You can also give a “hidden” option to the [toctree] directive, like
this:
.. toctree::
:hidden:
doc_1
doc_2
This will still notify Sphinx of the document hierarchy, but not
insert links into the document at the location of the directive –
this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.
This appears to say: Yes, what I propose is possible. But I can’t find a clue to how it’s done. Can anyone provide insight?
The RST documentation quoted by Sphinx as "The authoritative reStructuredText User Documentation" (see here) shows several styles for the formatting of numbered lists, among them the parenthesized style (see here):
(1) foo
(2) bla
However, Sphinx generates a style with dots from such RST source:
1. foo
2. bla
The Sphinx documentation only shows that dotted style (see here).
My question is: Is there any way to make Sphinx create the parenthesized style for the numbers?
* This is a bulleted list.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
See reStructuredText Primer in Sphinx documentation site.
On an article website using smarty template, I need to truncate the main content to create teaser. I can truncate by char but first paragraph length is totally unknown from article to article.
I want something smarter that just show the first paragraph:
Content:
This is my first paragraph and I want to display this and only this.
This the rest of the content and it is very long with a lot of words...
Teaser:
This is my first paragraph and I want to display this and only this.
So is the text to truncate wiki syntax or html at this point? If it's wiki the you should be able to do a search for \n\n using strpos php function (add it to the smarty functions in the security control panel if it's not one of the allowed ones already). Then you can do a substr function on the text and add the "..." or whatever after it.
If it's html then a preg_replace would probably be the best approach - something like
{preg_replace('/^.*?<\/p>/mis','$1"',$content)}...
...might just work (untested, sorry ;)
HTH
Reading through GitHub's help website, I've come across a very neat-looking procedure list.
From GitHub's Create A Repo Tutorial
I have read through GitHub's Markdown Tutorial as well as the Markdown Cheatsheet, but have not found any way to perfectly replicate this type of format.
The closest I have done so far was to basically put a blockquote after a number list entry:
1. > line 1
>
> line 2
2. > line 3
>
> line 4
And it looks similar, but, well, see for yourself:
Is this the closest I can get to GitHub's format?
Is there a proper Markdown syntax that I have missed?
If not, is there a way to achieve this in raw HTML?
If you look at the source of that page you can see that this is just a normal ordered list containing paragraphs:
<ol>
<li><p>In the upper-right corner of any page, click...
So to produce that HTML with markdown simply use the normal ordered list syntax:
1. First paragraph here.
2. Another paragraph here.
The particular appearance of that page is done by styling with CSS. It looks a little involved, using the ::before pseudo-element. If you want to replicate something similar have a look at the page with your browsers inspector to see the the styles. Experiment until you understand how it works and can create the effect you want.
If you are looking to create this effect on your own Github pages (e.g. a README) then I think you are out of luck, since you can’t control the CSS.