Within the markdown document, what is the proper syntax to go up one directory and then choose the file? It will be rendered online, so would html ../ be appropriate to put in the markdown syntax?
such as [some_description]andthen(../file_name.md)
I had to add the "and then" to get it to show up on stack....
Links work the same way in Markdown as they do in HTML. A relative path would work the same way.
[I'm a relative reference to a repository file](../blob/master/LICENSE)
which is from here: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#links
Related
I have a book with the following directory structure
book.adoc
chapters/chapter1.adoc
chapters/chapter2.adoc
chapters/chapter3.adoc
images/img1.jpg
images/img2.jpg
in book.adoc I include the chapters. The problem is that in each chapter I include images from the images directory. If I use a path relative to book.adoc then the images render when I generate the PDF of the entire book, but not when I generate a PDF of an individual chapter.
This is particularly annoying when working on a chapter and the HTML preview does not show the images.
Is there a way to specify the paths so it works in both cases? Is the only way to move the chapters up a directory?
Yes. Your documents can specify the imagesdir attribute. See the documentation.
If you specify imagesdir as a relative path, such as ./images, then you can have chapter-specific image folders that should allow your full and chapter-specific builds to work, as well as make the HTML preview work.
Context
I am using Sphinx to create technical documentation (not code-related). The input are several reStructuredText and SVG files. The output is created using the singlehtml builder (which is converted to PDF using weasyprint in a later step).
Problem
I would like to include a table of contents (TOC) in the final document. The default location for the TOC (sidebar) is not an option. I have to disable/hide the sidebar to generate a useful PDF.
Solutions (I have considered / tried)
toctree directive: Seems to only work with the sidebar, no matter what I try.
HTML Theming: I'm using it for styling the HTML output, but I would not know how to address the TOC issue.
Sphinx extensions: I wrote my own, but it's not very flexible and I'm still sure that others have already solved this problem.
Use latexpdf builder: Tried that and it solves the TOC problem, but it creates a few other problems and styling the document is so much easier for me using CSS.
Other tool than Sphinx: Is this a typical case of an XY problem? I would like to use reStructuredText and SVGs to generate a PDF, but I would be open to use something else than Sphinx.
Use the contents directive.
Here's the directive in its simplest form:
.. contents::
Language-dependent boilerplate text will be used for the title. The English default title text is "Contents".
An explicit title may be specified:
.. contents:: Table of Contents
As #mzjn already suspected, .. contents:: only lists the contents of the current file, but if I use .. include:: instead of .. toctree:: to include other documents, it works nevertheless. So what I'm currently using is this:
.. sectnum::
.. contents:: Table of Contents
:depth: 2
.. include:: intro.rst
.. include:: processes.rst
I'm writing a document using asciidoc and asciidoctor. So, I'm having a intro.adoc file and then bunch of section files. So, what I want to do is list them on to intro.adoc and add hyperlinks to them so that it will be easy to navigate.
For this I can think of two approaches:
First, I can use headers and associate a relative link to .adoc files in the same directory. So, that they will redirect to them. But I don't know how to achieve it. link: == section1.adoc[Section 1] is not working.
Second, using include::section1.adoc[]. Its working but its not a hyperlink.
What is wrong with it? or is there a easy way to do it.
Edit
If its not clear, I'm trying to achieve this # [Section1](section.md)(Markdown version) in asciidoc.
What about:
<<section1.adoc#Section1,your link>>
See:
https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/
I'm manually converting a MS Word document to asciidoc format.
By doing so I ran into an issue that I can't work around yet.
There is an example where I want to show the reader of how the syntax of a file link should look like.
So I used this as an example:
file:///<Path>/<to>/<Keytab>
Asciidoc now renders this pseudo link into an actual link and warns me about this while converting my asciidoc document into HTML and PDF.
Usually, I would simply use the [source] element to prevent the link rendering. But the file link is part of a table.
[options="header,footer",cols="15%,85%"]
|=======================
|parameter|usage
|keyTabLocation |file:///<Path>/<to>/<Keytab>
|=======================
Is there a way to prevent the rendering/convertion of the file link?
Okay, I found the solution. I had to escape the whole macro using a \ at the beginning.
So this did the trick:
[options="header,footer",cols="15%,85%"]
|=======================
|parameter|usage
|keyTabLocation |\file:///<Path>/<to>/<Keytab>
|=======================
We are considering using Sphinx where I work and it appears to do everything we need. However, I am having issues getting it to match the required corporate template, which requires there to be some front matter pages inserted between the title page and table of contents.
If text is text is placed above the master table of contents in the .rst file, then it is placed above the TOC in the HTML output, but it is moved to below the TOC in the pdf output. I've also tried adding a hidden toc, but that didn't work either. The content also gets placed after the non-hidden toc.
.. toctree::
:hidden:
frontmatter
.. toctree::
:maxdepth: 2
contents_of_document
I know this has to be possible since people have published books using this tool, but I can't figure out how to do it.
I've tried this with sphinx 1.4.0 and 1.4.1. Is this something I need to add a latex sty or cls file to make it work? I would prefer not to since we would like to use both the HTML and PDF outputs.
Thanks
It looks like I need to RTFM. It is in chapter 10 to of the sphinx manual:
’tableofcontents’ “tableofcontents” call, default ’\tableofcontents’. Override if you want to generate a different table of contents or put content between the title page and the TOC.
So it order to do this, you need to learn some LaTeX as you will have to manually (or programmatically) write the from matter separately from the reST documentation.