I am trying to add some html elements (like a div) in a custom theme, that wrap the mkdocs generated code blocks from the html output.
mkdocs has their fenced code blocks with the triple backticks ``` stuff ``` and when it produces the html output it creates <pre><code (some stuff here)> stuff </pre></code>. I was wondering if there is a way with custom themes that preserve the pre and code tags output with the highlight.js class attribute but also allow me to wrap it in a custom div so that I can put the code blocks in a container with some other elements.
The code blocks are generated by the Markdown parser, not by the MkDocs template. In fact the HTML generated from Markdown for a page is passed to the template as a single block. Therefore, to alter the HTML output by Markdown, you need to use a Markdown extension. MkDocs uses Python-Markdown and fully supports Python-Markdown extensions.
If one exists, you could use an existing third party extension which provides the desired behavior. Alternatively, you could create your own custom extension.
Related
I'm trying to include Shield IO Badges in the README.rst file for a GitHub project I am working on. Shield IO Badges have the functionality to encode for two links (one on the left side of the badge and one on the right side of the badge) and I would like to include this in the project README. From https://shields.io/, in order to use the dual link functionality, the badge must be encoded in a HTML <object> tag. reStructuredText has the raw function and can include HTML code snippets in the files which is parsed and included in the README. The PyCharm interpreter can parse the HTML properly and the dual link functionality is present. However, when I push the file to GitHub, the HTML is not being parsed at all. Was curious if there was a work around to get this functionality in a GitHub README file (Doesn't necessarily have to be reStructuredText).
Example:
.. raw:: html
<object data="https://img.shields.io/static/v1?label=Question&message=Unanswered&color=lightgrey&link=https://stackoverflow.com/&link=https://stackoverflow.com/questions/66716288/embedding-shields-io-badge-html-in-github-readme-rst"></object>
Example Badge Image:
Link to Shield IO Static Badge with Dual Link Functionally:
https://img.shields.io/static/v1?label=Question&message=Unanswered&color=lightgrey&link=https://stackoverflow.com/&link=https://stackoverflow.com/questions/66716288/embedding-shields-io-badge-html-in-github-readme-rst
It's not possible. Github strips links from SVG's in Markdown and reStrcturedText. See this issue on Github.
How to specify the link of left and right on GitHub #5593
It works if you wrap an <img> tag with the Shield.io badge with a <a> tag containing the link you want. I know using HTML in markdown is frowned on but this is the only way I've found to make this work how you want it to.
<img src="https://img.shields.io/static/v1?label=Question&message=Unanswered&color=lightgrey&link=https://stackoverflow.com" />
If I have an html file somewhere in the same folder as a markdown document, is there any way to embed the entire file inside a markdown document, so that the html will be rendered correctly (not just the code displayed)?
Markdown doesn't support includes out-of-the-box. You need to use one of the existing flavors or static site generators that support markdown or/and HTML inclusions. For example, DocFX
You can't include other Markdown files in Readme (Readme is usually Markdown file). You can use the "Quote" (See example below)
This is Quote
> This is Quote
You can see my Markdown guide here
For most of my project's documentation I prefer a standard sphinx layout. However for the landing page I would prefer to use custom HTML/CSS/JS without any of the layout, TOC, or sidebars of the normal sphinx site. Is there a way to include a raw HTML standalone page in a sphinx-generated website in a way that completely disregards the normal layout of the rest of the site?
As a counter example I know that I can include raw HTML bits into a page using the following (see also this question)
.. raw:: html
:file: myfile-html
However this just embeds a file within the normal layout. I would like to have a completely standalone HTML page.
I just ran into this problem myself, and the way I solved it was to simply include the html file in my source/_static folder, then refer to it with a relative link.
So if source/_static/my_standalone.htm is the path where I have my non-generated HTML file, and the .rst file where I want to type my link is at source/otherfolder/index.rst, I write it like this in my rst:
Link to my non-Sphinx HTML file
===============================
To get to my standalone, non-generated HTML file,
just `click here <../_static/my_standalone.html>`_ now!
I have been working on a personal "how-to" guide, chronicling and keeping a journal of my studies as I go along.
I now have a, almost too long block of code that, when I've encountered this length of code myself, its always frustrating trying to highlight JUST the block without it highlighting the whole page, or not enough.
So, my question is, for rst (reStructuredText) .. code-block::'s, is there an add-on or a way to add in a copy button, for automatic highlighting or automatically adding the text to the users clipboard? Or would this be a more html-literal type of code I'd have to include in the build and reference it in the code block? If so, what would something like that look like as well?
There is a dedicated package for that called sphinx-copybutton.
It's straightforward to use.
# Install
pip install sphinx-copybutton
# Declare it in the conf.py
extensions = [
...
'sphinx_copybutton'
...
]
And that's it, generate the doc and a copy button will appear automatically in each code block.
In Sphinx projects, the presentation of the HTML page is controlled using a template language (Jinja2 by default). So you can make your pages more interactive by adding Javascript to the HTML template file(s) and it will get inserted when Sphinx uses that particular template file to render a page.
Locate your templates directory by searching for templates_path in your conf.py
Jinja templates can extend one another, so you probably want the file that begins with {% extends "basic/layout.html" %}.
Once you track down where in the sequence of extension you want to make your change, you need to combine:
The section of the page where you want this to take effect (typically the main block)
the CSS with a class for code blocks (eg. in mine it's class=highlight). The .CSS file might well be in docs/source/_static/
A javascript snippet to create the button and write to the clipboard (eg. https://clipboardjs.com/)
Next, build the Sphinx project locally (make html) until you have it dialed in and then push your source repo to readthedocs.
I'm using github pages for my site.
I generate my pages from markdown to html using the built in Jekyll support.
The built in markdown renderer rdiscount does handle tripple backtick codeblocks.
but it just applies the language as a css class on the <pre>
What should I do to get Jekyll to highlight code on page generation?
I've also tried to copy all stuff from octopress, but whith no luck, the codeblocks still come out with a css class only.