I'm looking to add meta tags to my sphinx document for the opengraph properties.
I see that sphinx has this meta directive
.. meta::
:description: The Sphinx documentation builder
:keywords: Sphinx, documentation, builder
But how do I use it to tags with the property attribute like <meta property="og:title" content="<title>" /> -- I only see examples with the name attribute?
I see that there's also the sphinxext-opengraph extension, but it looks like that uses conf.py to specify the tags, and I want to manually set the tags for each RST document.
The aforementioned sphinxext-opengraph extension currently has a PR for setting the values per page. The PR is effectivley done so a new version should be released very soon.
Edit: The PR has been merged. You can now set any tag by adding field lists to the top of the page like so:
:og:description: New description
Page Title
==========
For more info refer to the docs or the readme in the repo.
Edit 2: Currently relative image/video/audio file paths are broken on purpose, this will be fixed with #53
Related
How to create a custom Id for headlines in Sphinx (Jinja)?
Sphinx defines Id same with the headline text by default, but I want to define a different Id
If you write this in text file :
Headline text
=============
After converting it to HTML file by Sphinx, it looks like this:
<span id="headline-text"></span><h2>Headline text<a class="headerlink" href="#headline-text" title="Permalink to this headline">¶</a></h2>
But I don't want this Id and I want to define my own custom Id for this tag
If text isn't English, the default value is 's-id{number}', which number sets by Sphinx.
Now I want to write something in another language and I'm looking for a way to change it.
After many searches, I came up with a way like the following, but the problem is that when I look at the HTML source, I see that it still has its own ID next to mine like following:
.. _my-custom-id:
مثال سرتیتر
============
And after converting to HTML:
<span id="s-id1"></span><span id="my-custom-id"></span><span id="id1"></span><h1>مثال سرتیتر<a class="headerlink" href="#my-custom-id" title="Permalink to this headline">¶</a></h1>
As you can see, this method still doesn't work and Sphinx still defines its default ID.
What is the solution?
Is there a setting I can tweak in conf.py to ensure that image previews are generated for links to my index.html?
I think I need to put a link to the image inside:
<head><meta name="og:image" content="https://.png" /></head>
Maybe a setting on one of the html_* options? I read through them, but did not see anything.
https://www.sphinx-doc.org/en/master/usage/configuration.html
Page to link to: https://aiqc.readthedocs.io/en/latest/
One of many meta tags available in:
https://github.com/wpilibsuite/sphinxext-opengraph
conf.py
extensions = ['sphinxext.opengraph']
ogp_image = "https://raw.githubusercontent.com/aiqc/aiqc/main/docs/images/aiqc_logo_banner_controlroom.png"
It even has a field for user-defined <meta> tags.
On the main page of every repository in GitHub or BitBucket it shows the Readme.md in a very pretty format.
Is there a way to make the same thing with ruby? I have already found some gems like Redcarpet, but it never looks pretty. I've followed this instructions for Redcarpet.
Edit:
After I tried Github's markup ruby gem, the same thing is happening.
What is shown is this:
And what I want is this:
And I'm sure it's not only css missing, because after 3 backquotes (```) I write the syntax like json or bash and in the first image it is written.
Edit2:
This code here:
renderer = Redcarpet::Render::HTML.new(prettify: true)
markdown = Redcarpet::Markdown.new(renderer, fenced_code_blocks: true)
html = markdown.render(source_text)
'<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>'+html
Generated this:
Github provides its own ruby gem to do so: https://github.com/github/markup.
You just need to install the right dependencies and you're good to go.
You need to enable a few nonstandard features.
Fenced code blocks
Fenced code blocks are nonstandard and are not enabled by default on most Markdown parsers (some older ones don't support them at all). According to Redcarpet's docs, you want to enable the fenced_code_blocks extension:
:fenced_code_blocks: parse fenced code blocks, PHP-Markdown style. Blocks delimited with 3 or more ~ or backticks will be considered as code, without the need to be indented. An optional language name may be added at the end of the opening fence for the code block.
Syntax Highlighting
Most Markdown parsers to not do syntax highlighting of code blocks. And those that do always do it as an option. Even then, you will still need to provide your own CSS styles to have the code blocks styled properly. As it turns out, Redcarpet does include support for a prettify option to the HTML renderer:
:prettify: add prettyprint classes to <code> tags for google-code-prettify.
You will need to get the Javascript and CSS from the google-code-prettify project to include in your pages.
Solution
In the end you'll need something like this:
renderer = Redcarpet::Render::HTML.new(prettify: true)
markdown = Redcarpet::Markdown.new(renderer, fenced_code_blocks: true)
html = markdown.render(source_text)
As #yoones said Github shares their way to do it but to be more precise they use the gem "commonmarker" for markdown. Though as far as I can tell this thing does not give the full formatted HTML file but only a piece that you insert into <body>. So you can do it like I did:
require "commonmarker"
puts <<~HEREDOC
<!DOCTYPE html>
<html>
<head>
<style>#{File.read "markdown.css"}</style>
</head>
<body class="markdown-body Box-body">
#{CommonMarker.render_html ARGF.read, %i{ DEFAULT UNSAFE }, %i{ table }}
</body>
</html>
HEREDOC
Where did I get the markdown.css? I just stole the CSS files from an arbitrary Github page with README rendered and applied UNCSS to it -- resulted in a 26kb file, you can find it in the same repo I just linked.
Why the table and UNSAFE? I need this to render an index.html for Github Pages because their markdown renderer can't newlines within table cells, etc. so instead of asking it to render my README.md I make the index.html myself.
This block of AsciiDoc will create a title and current revision information:
Writing Documentation using AsciiDoc
====================================
v2.0, February 2003:
Rewritten for version 2 release.
The docinfo_generator will extract this information from a comment block in an AsciiDoc-formatted document, then embed it in the docinfo.xml file:
////
:revinfo:
v1.0.3, Joseph HERLANT, 2013-08-18:
It matched only the last group. Correcting this to get only the first of each groups
to avoid getting data in the content of the document if defined in the header
v1.0.2, Joseph HERLANT, 2013-07-05: Adding a verbose flag to show more informations while processing data.
v1.0.1, Laurent LICOUR, 2013-06-05:
Correcting documentation.
If attributes were absent, the document did not generate. This is corrected now.
////
While useful, the revision history won't be included in the asciidoc-generated HTML (it might be in the a2x-gerneated HTML, but I haven't tested this).
I would like to find a way to embed the entire revision history in a asciidoc-formatted document, then have it displayed (ideally) at the end of said document as a table.
Is this possible?
You can define the sections [header] and [footer] in asciidoc.conf or in a separate file an then insert it with -f command line switch. Those sections contains HTML code, insert the {attr-name} where you need to insert your information. For example
[header]
<html>
<head>
<title>{title}</title>
</head>
<body>
[footer]
</body>
</html>
set the document title in the header tag.
Actually I use those section as a HTML template, so all the HTML page is defined there, the AsciiDoc compiled code will be inserted between the two sections.
I would like to create a pdf book using asciidoc. The title page should include the title, subtitle and an image. So far I could not find any documentation on how to achive this.
Intuivly I would do something like
My book title
=============
:author: myself
:toc:
image:images/titelimage.png[width=400]
but this just adds image:images/titelimage.png[width=400] as a subtitle. What I would like to have is something like
My book title
<titleimage>
subtitle
Is there a way to do this in ascciidoc? If not, what do I need to do to get this?
If you're using asciidoctor-pdf you can define an attribute for the logo. It will place the image above the document title.
:title-logo-image: images/titelimage.png
See an example pdf here and the raw adoc.
If anyone is still looking for this answer, this is the correct way to do it (using asciidoctor-pdf):
= Book title
Authors
:front-cover-image: image::./images/title_page.png[]
This gives you the image by itself as the first page followed by a page that shows the title, authors, revision etc.
If you want the image on the same page as the title and author, you need to use :title-logo-image: instead.
If you want a PDF using the docbook 4.x output you should:
Generate a docinfo file with an image for the front page. This is an XML file looking like the following example. It is discussed at http://www.methods.co.nz/asciidoc/userguide.html#X87
Example:
<mediaobject>
<imageobject>
<imagedata align="center" depth="400" fileref="../images/tiger.png" />
</imageobject>
</mediaobject>
<subtitle>Subtitle of this book</subtitle>
Then, customize your DocBook stylesheets to include the media element for the title page (by default the stylesheets do not include this). http://www.sagehill.net/docbookxsl/TitlePagePrint.html
DocBook 5 includes a cover element in its stylesheets.
This:
= The Book's Title
:author: First Last
:email: first.last#company.com
:toc:
:toc-placement: preamble
:doctype: book
image:./images/title_page.jpg[]
Produces:
My book title
first.last#company.com - first.last#company.com
Image
Table of Contents
...
you just need to add a empty line between the toc and the images: instruction. That's how asciidoc kinda separates blocs.