Is it possible to create an intra-document link with sphinx, such that the displayed text is independent of the link and destination?
Currently, I make intra-document links like so:
.. _Label_For_Section:
===============
Name Of Section
===============
The link :ref:`Label_For_Section` is rendered as "Name Of Section".
The link Label_For_Section_ is rendered as "Label_For_Section".
What I want is a way to have a link, where the destination text, link label, and displayed link text can all be different strings. Eg a link to a section called "A" with a label .. _B: which is rendered as "C"
Note
I noticed that other kinds of links (eg external hyperlinks) are similarly constrained, and I figure the solutions may look similar, however I am looking specifically for a solution for intra-document links.
See Cross-referencing arbitrary locations, specifically the ref role.
:ref:`Link title <label-name>`
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 am adding a hyperlink into the comments for my code for future reference. The hyperlink is being added by copying the url from Safari and then pasting it into Xcode.
The problem is that I can't control the hyperlink now that it has been pasted into my code and it is being modified when additional text is added.
Example URL: https://link.to.resource/DID/
How I want the link to be displayed: Device ID (listed in https://link.to.resource/DID/.)
How can I add the additional text without modifying the link location? When I add ./ to the end, it becomes part of the link and the address no longer works.
The simplest solution is to include a space or closing paren at the end of the link.
You can also use comment markup to add a link to Xcode's Quick Help Documentation.
/// Device ID (listed [here](https://link.to.resource/DID/))
This will create a quick help description that looks like this:
If you are really set on a period at the end of the link, you can add it inside the [] at the end of the link text. This is what Apple does in one of their examples for link markup. This adds a period at the end, but the period is styled as part of the link text.
/*:
For more information, see [The Swift Programming Language.](http://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/)
*/
Apple's Link Markup Documentation: https://developer.apple.com/library/content/documentation/Xcode/Reference/xcode_markup_formatting_ref/Links.html#//apple_ref/doc/uid/TP40016497-CH18-SW1
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.
Say I have a normal documentation part and additionally a glossar, both build in the same sphinx project.
Is there a way to link a word with let's say a headline on another page without using a normal static link?
If there is no other way than a static link, is there a possibility to introduce IDs?
You can create a link to any spot in your project using cross references. For example:
.. _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`.
I am using Confluence 4.0.3, I am trying to create a PDF layout/stylesheet so that it would grab the main title from the page content and move it to the title page.
What I have tried so far:
use the way that confluence suggests - it did not work well at all because it came with extra toc (np, I can hide it) and extra page content because it requires me to export from the parent level for it to work
I define a macro which contains the page title and I can use css to make it land on the title page. This works however if I was to export multiple docs this could pose a issue
Style the h1:first-child, this works but again on multiple docs this would be an issue.
Question: Is there a good way to do this on multiple doc exports? If not, does the page title have its own class that I can target instead of the h1:first-child? I tried h1.pagetitle (in their documentation) but it does not work, thanks
I used a user defined macro to put the title in and use the PDF export css to position it on the title page. This works as long as you are only exporting 1 document at the exporting level. If you are exporting 2 or more docs from the same exporting level then you can only define 1 of the macros or else they will all be at the same position on the title page.
This seems like the easiest way I found to implement something like this.
I would try employing a minor work-around. You could use a .asp page, which is located off of confluence, to pull the the pdf title and display it how you like. Then you can use an html-include macro to display the .asp page, and the pdf title it shows, wherever you like on confluence.