This is the beginning of an AsciiDoc document, where the author is specified:
= Writing Documentation using AsciiDoc
Tom White <twhite#mymail.com>
v2.0, 2020-11-06
:toc:
The author name is accepted by the AsciiDoc processor, i.e. no error is produced, but it is not shown in the output document.
How is it possible to make the author's name visible?
If you are using the default Asciidoctor templates for HTML output, the author and their email address is included beneath the document heading.
If you are using a custom template, then the author and email address are available as attributes that you can use at any location within your document, {author} and {email} respectively.
For details, see: https://asciidoctor.org/docs/user-manual/#author-and-email
Related
I'm writing some text that will be converted to HTML, as a long single page.
Can't figure out how to make links to sections as in HTML using #some-id, so that a user when clicking it will go up or down the web page to
<h2 id="some-id">Section A</h2>
<p>Lot's of lines</p>
Go to section
What you're referring to is called an "internal cross reference".
The markup for an internal cross reference is:
<<id,caption>>
where id is an element on the page that has an identifier, typically a title, and caption is optional text that should appear in the link.
You can link to titles that have auto-generated ids, but the formation of the ids could vary based on the attributes idprefix and (for Asciidoctor) idseparator. The default is to make the title text lowercase, prefix with an underscore, and replace spaces and other punctuation with underscores. The id for the title "Let's make a game!" would be _lets_make_a_game.
It is often better for you to specify your own id that will remain stable even if you edit the text of a title. You can do so with:
[[id,label]]
where id is the identifier you want to specify, and label is the optional, default label that may be used for the cross reference (if the cross reference itself doesn't specify a caption).
If the element that your cross reference points to is a title, you can omit the caption and the label, and the link will use the title's text as its own text.
For Asciidoc, see: http://asciidoc.org/userguide.html#_internal_cross_references
For Asciidoctor, see: https://asciidoctor.org/docs/user-manual/#internal-cross-references
Usage Example:
This is how we assign an ID:
== Debug Running Pods [[debug_running_pods]]
Refer to an ID:
<<debug_running_pods>>
Another option is to use the link: macro. Here's an example from one of my Asciidoctor docs:
link:#_explore_the_public_directory[17.4. Explore the `public` directory]
Info about this is in https://asciidoctor.org/docs/user-manual/#url. Here's an excerpt from the relevant part:
When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the link macro.
I have just recently (yesterday) started using sphinx and read the docs for my project.
Till now I am happy with the Html documentation but the pdf version includes all the articles That appear in the index within the Contents heading. And the Documents orignal content/index is simply comprised of two links.
Please help.
The documentation is at http://todx.rtfd.io and the pdf is here.
When generating the PDF, Sphinx is always adding the content that is referenced via a .. toctree:: directive exactly where the directive is placed.
In contrast, when generating HTML, Sphinx is placing the content after the file that contains the toctree.
In this aspect, PDF generation and HTML generation are simply inconsistent.
Thus, you should place all content of the index page before the table of contents.
In case you want to provide an overview of the most important sections inline, you can use a list of references. Then, you might want to hide the toctree using the hidden property, for example like this:
Contents
--------
- :ref:`quickstart`
- :ref:`userguide`
Features
--------
- Fast
- Simple
- Inituitive
- Easy to Use
- Offline
- Open Source
.. toctree::
:hidden:
quickstart
userguide
To reference a section using reStructuredText in Sphinx, I can do:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
as explained here.
This results in the section being referenced by title, that is I get the line:
It refers to the section itself, see Section to cross-reference.
(where Section to cross-reference links to the beginning of the corresponding section)
I'd like to get instead:
It refers to the section itself, see 2.1.
where 2.1 is the section's number.
Is there a way to accomplish this using reStructuredText in Sphinx?
The numsec Sphinx extension does what you want. The source code is here: https://github.com/jterrace/sphinxtr/blob/master/extensions/numsec.py.
The extension is part of the "Sphinx Thesis Resource" package developed by Stack Overflow member jterrace. See https://github.com/jterrace/sphinxtr.
I have a Restructured Text document which several hierarchical sections, such as:
Main title
##########
Text under the main title.
Sub-section
===========
Text under the sub-section.
This works great, I get the correct HTML formatting when I compile it using Sphinx.
My question is: how can I go up a hierarchy level so I can add more text after a few sub-sections?
For example:
Main title
##########
Text under the main title.
Sub-section
===========
Text under the sub-section.
In my CSS, sub-section is indented.
I want this paragraph to be rendered as part of the Main title section,
not the sub-section.
I'm basically looking for a way to go up a level in the hierarchy.
Is this possible?
Thanks!
It's not possible to go "up" the hierarchy without starting a new section at the level you desire. Document section structure doesn't work that way. Changes in section level must be preceded by corresponding section titles. Using indentation to signal a section-like structure should only be used in a limited local scope.
What you're describing isn't a subsection, it's a topic. Docutils has a directive for that:
.. topic:: title
Topic text.
May include multiple body elements (paragraphs, lists, etc.).
There is also a "sidebar" directive for a similar structure, but typically for a parallel topic that's off to the side. The "rubric" directive may also be of interest.
See http://docutils.sourceforge.net/docs/ref/rst/directives.html for details.
I put references in a yaml metadata-header:
references:
- id: fenner2012a
title: One-click science marketing
author:
- family: Fenner
given: Martin
...
(described here: http://johnmacfarlane.net/pandoc/README.html#extension-citations)
and I can cite this reference with See [#fenner2012a]....
This will create an output in the pdf like this: See ("One-click science marketing")... with no hyperlink on the reference.
Instead of the title I want to have auto-incremented number: See [1] with [1] being a hyperlink to the source. How can I achieve this?
Instead of the title I want to have auto-incremented number: See [1] with 1 being a hyperlink to the source. How can I achieve this?
Many CSL styles have a numeric format; you can try ACM Computing Surveys.
To specify the style, pandoc's documentation says:
These files are specified using the --csl option or the csl (or citation-style) metadata field.
There's one caveat when going to PDF, however. I haven't found a way to get the hyperlinking to work.
That is, you'll get See [1] but there is no hyperlink.
Edit: You can get this to work by using the following setting in meta-data:
link-citations: true
You can get hyperlinks in PDF by using LaTeX's way of formatting references. But I think you'll have to convert your reference to .bib format and specify it in your metadata:
bibliography: references.bib
pdf:
cite-method: biblatex