I'm using sphinx to generate the documentation of a python project and I'm making heavy use of external links. I'd like to build html and latexpdf outputs with these as clickable links (which is the default), but also a PDF version that will be printed, with these links showing up in footnotes.
In short: is there a way to write external links in a .rst file like this:
Ask a question on `my favorite Q&A website <http://stackoverflow.com/>`_.
and have a special output that will interpret this as if it was a footnote written like this:
Ask a question on my favorite Q&A website [#SO]_.
.. [#SO] http://stackoverflow.com/
while keeping the normal behavior (clickable link without a footnote) in other outputs?
Jongware's comment made me look at parts of the sphinx documentation I didn't see, and I realized there actually is a configuration variable that does what I want:
latex_show_urls = 'footnote'
As I wanted to be able to generate the usual pdf and the one with the footnotes without changing the conf.py file, I left the default value and added the following rule to the sphinx's Makefile:
.PHONY: printpdf
printpdf: SPHINXOPTS+=-Dlatex_show_urls=footnote
printpdf: latexpdf
This rule calls the regular latexpdf rule, adding -Dlatex_show_urls=footnote to the options given to sphinx-build.
With this, we can generate the PDF to be printed (with footnotes) with:
make printpdf
And if we want a regular PDF, without the potentially numerous and (here) useless footnotes, the regular rule still does it:
make latexpdf
Related
I have a book project in RMarkdown, but since I do not use Knitr or other RMarkdown specific features I am considering switching to pure Pandoc to remove the R burden from the dependencies.
For what concerns PDF and ePub output it seems all straightforward to me, but I have some troubles with the HTML output. In fact Pandoc generates a single HTML file with the entire book.
With Bookdown I used the gitbook HTML output which generates a page for each section and each page have the complete TOC on the left sidebar and its footnotes and partial bibliography on the bottom.
To achieve this I thought to write a md file for each section and convert them one by one with Pandoc (for the HTML output, and merge them to one unique file for converting to PDF and ePub), but in this way I cannot have references across sections, have a full bibliography at the end and also easily create a TOC.
So my question is if there is an easy way (e.g. a Pandoc filter or a script) to generate an HTML book (similar to gitbook in behavior, the style doesn't matter) without installing R and Bookdown?
Pandoc follows the philosophy of only writing files that have explicitly be specified on the command line. This is why no such feature is not built in.
It would be possible to do what you want with the help of a custom writer. The basic would be doable in a few lines of Lua code, but it's likely that you'd have to implement all bookdown features yourself.
The best (IMHO) alternative is to use Quarto, a standalone tool built on top of pandoc, created in part by the authors of bookdown. That way you can remove R from your dependencies but retain the features of bookdown -- and more.
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.
I am trying to write a jekyll plugin that will take a normal markdown file and provide some extra functionality on top of it. In particular, I need to do some (not actually) fancy things with tables. I know you can write straight HTML into a markdown file, but there is a requirement that the content folks don't want to / can't edit HTML.
As an extra wrench in the works, the mobile layout has a UX requirement that I essentially have to render the table as a group of divs as opposed to a table.
My initial thought was to pass the {{page.content}} variable to a ruby function extending Liquid::Tag. From there I was planning on parsing the markdown file and either:
1. If normal non-table markdown, use as normal
2. If table markdown, look for custom identifier in markdown, do what needs to be done (e.g. add class, etc)
If I do something like this:
def render(context)
content = Liquid::Template.parse(#markup).render context
end
It renders the context as a normal markdown file. However, I want to break up the context variable and work with the pieces before rendering. I've tried a few different approaches that I've gotten from the jekyll docs and Stack Overflow and gotten nowhere.
Does anyone have any experience with this? I am heading down the right path? For what it's worth, Ruby/Jekyll/Liquid is fairly new to me, so if you think I may have missed something fairly basic and obvious then please let me know.
A markdown table tool for editors !
markdownify your table in http://www.tablesgenerator.com/markdown_tables
paste the markdown result in http://prose.io/
done
I don't know other way to simplify editor's work on Jekyll, but I'll be very interested in earing from your project. Good luck.
I am trying to convert from html to pdf with Pandoc. The output is pretty nice, still with the command pandoc index.html -o output.pdfI lose all my internal links (from table of contents to chapters, from text to footnotes, etc).
In my HTML this is the outdegree link
<p class="calibre18"><span class="calibre8">CHAPTER ONE</span><br class="calibre19"></br>The Ever Expanding Domain of Computation</p>
which then lands here
Chapter 1 makes the case that because of...
and here
<p class="calibre18"><span class="calibre8">CHAPTER ONE</span><br class="calibre19"></br>The Ever Expanding Domain of Computation</p>...
Is there any way to keep all the links also in the output?
The Pandoc User's Guide section on Internal Links says
Internal links are currently supported for HTML formats (including HTML slide shows and EPUB), LaTeX, and ConTeXt.
This suggests that internal links aren't currently supported for PDF output, even though the PDF output is generated via LaTeX.
Internal links should work straightforwardly in PDF. However, for printing purposes, the default is not to color them. Have you tried clicking on the text that should be a link?