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.
Related
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
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.
I am working on creating a Sphinx theme based on Accelerated Mobile Pages (AMP). While creating it, I came to realize that since AMP uses amp-img tag in place of the img tag. Is there a way to convert all the img tag in the sphinx generated docs to amp-img
There is nothing out of the box. The easiest option is to post-process your HTML output from Sphinx.
I have SVG image file with several nodes each is associated with URL. If I open this file directly in browser I can click on each node and it will open different URLs. However when I use this picture in my Sphinx documentation it doesn't work - picture rendered as a whole so I need to open it by View Image and only then I can click on nodes.
I'm using standard image directive:
.. image:: myfile.svg
Probably I need to use something else?
Sphinx generates <img> tags for images, which makes sense in most cases. However, to have the links inside the svg be clickable, you should use an <object> tag, i.e.:
.. raw:: html
<object data="myfile.svg" type="image/svg+xml"></object>
(Regarding the GitHub issue you linked to, I don't think there's a lot that Sphinx can do here—it's really quite complicated—short of introducing a new option to the .. image directive that lets the user specify whether to render as an img or object tag.)
One simple solution would be to add a link to the svg file in this .. image:: myfile.svg command:
.. image:: myfile.svg
:target: _images/myfile.svg
Take care of checking the relative directory where the images are copied when the html files are generated. By default, it should be _images/.
This way, you can click the SVG file, to see it in a plain page, and then click on it as usual (not a perfect solution but still..).
I am probably misunderstanding the OP's requirements, but why not just include the SVG into the sphinx documentation as html? This appears to work for me:
.. raw:: html
:file: images/image.svg
To include clickable svg links within sphinx I did the following:
.. raw:: html
:file: ../graphs/pymedphys_analysis.gamma.svg
See:
https://raw.githubusercontent.com/pymedphys/pymedphys/1915b9496e93782bdac7dcebff7e26e470e5ff57/docs/graphs/graphs.rst
This then freed me to write the following within an imported style sheet:
svg {
width: 100%;
}
https://github.com/pymedphys/pymedphys/blob/f4d404fa1cf3f551c4aa80ef27438f418c61a436/docs/_static/style.css
This made the svg fit the container as desired.
See:
https://pymedphys.com/developer/dependencies.html#pymedphys
I like this way
.. raw:: html
<a href="https://www.google.com/">
<img src="https://img.shields.io/static/v1?&style=plastic&logo=appveyor&label=Google&message=link2google&color=FF0000" alt="No message"/></a>
I'm still looking for a better solution myself, but I ran into the same problem and used this workaround.
You can use the download directive to give the user a link to the file.
:download:`svg <images/image.svg>`
Is it legitimate to set the canonical link to the pound symbol as shown below, or am I required to enter a physical page name?
<link rel="canonical" href="#">
When testing this, the pound setting does not generate a validation error (ala #development=1). In my scenario, the page using this layout file will not have an alternate "regular HTML" version. The only version will be the AMP HTML version.
For additional context, I'm experimenting with an MVC site that will use AMP HTML. To keep my layout file simple, I'd prefer to use the pound symbol rather than extracting the child page name and applying that to the href attribute. I know how to apply the URL to the partial view via code like so:
<link rel="canonical" href="#HttpContext.Current.Request.Url.AbsoluteUri">
I'm just curious if it's legitimate AMP HTML to use the pound symbol instead. Thank you.
From the documentation:
Required markup
AMP HTML documents MUST:
contain a <link rel="canonical" href="$SOME_URL" /> tag inside their head that points to the regular HTML version of the AMP HTML
document or to itself if no such HTML version exists.
So instead of using href="#", you should have it point to itself in order to stay consistent with the AMP specifications.
Validation is evolving, the validator doesn't catch all issues today. The issue with using "#" or any relative URL is that when this document is served elsewhere, such as cdn.ampproject.org, that relative URL will no longer point to your intended canonical. You should instead use an absolute URL <link rel=canonical href="URL">.