I have two markdown documents; A.md and B.md. The A document includes a link to B using the tag (B)[B.md]. That link works great when navigating markdown documents.
Now I want to export all my markdown files to HTML as part of a release documentation package. The issue is that in the exported HTML the link points to B.md when what I really want it to point to is the newly exported B.html.
Anyone have any ideas on how to automatically update links?
I am currently using pandoc to export to html because it has a command line interface and therefore I can script its execution.
Right now my workaround is to update A so that it links to the html version of B, [B](b.html). This allows my html exported documents to work but breaks navigation within the original markdown files. Alternatively I could replace the links myself as part of the script but that sounds painful.
What I am really looking for is a way to export a collection of markdown files as a standalone documentation package.
You can use a simple Lua filter to change the link from .md to .html:
-- file: change-links.lua
function Link (link)
link.target = link.target:gsub('.md$', '.html')
return link
end
Adding the parameter --lua-filter=change-links.lua to your call to pandoc should be all that is needed.
See also this related question.
Related
I am using GitHub pages for my website!. I add new pages as md files, which nicely works when there are no figure included.
However, when I did some analyses in RStudio (.Rmd file) the final md file does not display any figure or leaflet object when used with GitHub pages. When I include the html file directly everything works nicely except for the fact that it does not look like the rest of my site (which I want, of course). I have to mention that I use an adapted version of the beautiful-jekyll template! by Dean Attali!.
I was wondering why it is not working. Maybe it is due to an issue with some css file. Remember: When I load RStudio's html output everything is displayed as intended. Here! is a link to the respective GitHub repository.
I hope that there is someone out there having an answer to this.
Thanks!
Note: In case you cannot access the repository/files, you can download the files here. It's the .Rmd as well as the output as .md and .html, and the .RData. As said before, including the .html works, but doesn't have the formatting according to my .css. .md fails in the way it doesn't show figures or leaflet objects, but the formatting is fine. Have a look.
Now, the issue with missing figures was solved.
One has to be careful where to place the folder containing all figures. It has to have the same path as the .md files.
Additionally, the embedding has to be changed in the .md file from  to .
That's it for the figures. Now I'm looking for a smart way of handling the leaflet objects.
Before asking this question, I read the following two questions in Stack Overflow to avoid duplicate questions:
1) #Render.Scripts in plain .html file - not in .cshtml
2) Rendering the script bundle in a plain HTML page
May I know how to use script bundles in plain html file (something like #Scripts.Render("~/bundles/angular") in cshtml)?
I want to bundle more than one script file (to compress and load them together) and use the bundle in plain html. This bundle is going to be used in more than one html file.
Please advise.
You should use a script minifier/bundler, like https://jscompress.com/. Choose the "Upload Javascript Files" tab, and upload all the scripts you want there. It will produce a single, minified and bundled file, just like ASP.NET would. You can then include that single file in your code just like you wrote.
How do I convert an HTML file with content folder to a self-contained HTML file which can be viewed from anywhere with its images etc.
How can it be done so that it's also editable and stays self-contained, post-edit?
I basically need to make HTML file based documentation which can be viewed from anywhere. Unfortunately it HAS to be HTML, otherwise I would have made PDFs
You can use pandoc, it has an option to create self-contained html files https://pandoc.org/MANUAL.html#option--self-contained.
If you start with html, this is the command.
pandoc in.html --self-contained -o out.html
This tool can do a lot more things, for example, you can also generate html from markdown files or generate pdfs instead.
The most direct way is to convert all asset urls to data: urls. (There are online coverters available that will take a provided asset and produce a data: url from it.)
A possibly simpler way is to convert image and font urls to data: urls while instead inlining scripts and css.
Edit: Possibly of interest: inliner, a Node utility for doing this kind of thing. "Turns your web page to a single HTML file with everything inlined". Also performs a number of minifying optimizations.
I don't know exactly what you're envisioning, but HTML was never meant to be fully self-contained. There may be some loopholes that allow it in the end, but to my knowledge there are no premade tools that do this 'conversion'.
It would require the following things:
Converting all linked style sheets and scripts to inline style sheets and scripts. This means that whenever there's a <script src="http://url.to/foo.js"></script> you'll have to download foo.js and include it as such: <script type="text/javascript"> [this is the content of foo.js] </script>. Something similar applies to CSS and other linked source files.
Downloading all linked media (images mostly, I presume) and converting them to blobs (a service that provides you with a base64 blob you can use within a HTML file is https://www.base64-image.de/). This means replacing <img src="http://url.to/image.jpg" /> with <img src="data:image/png;base64,[converted image data goes here] />.
So there's gonna be some manual labour involved there, but it probably can be done (almost) fully.
Possibly there's a way to accomplish what you're wanting to do another way though, what exactly is your reason for wanting this?
Here's another option: write your documentation in markup, then use a tool such as "Marked 2" (http://marked2app.com) to convert to self-contained html. Works slick. Plus you can go back and edit the markup any time you need to update your documentation, then simply re-export your html file.
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.
When I decompile I get an hhc file and a hhk file and no index.html. Can I get MS HTML Workshop to generate a html table of contents index.html file instead when decompiling? If not is there any other free software I can use?
Afaik no. Creating a basic toc->html export would be very easy, since it is essentially a XML to html transformation, but it probably won't be in the style of the rest of the CHM.
Maybe one of the Unix CHM viewers perform such step to view the TOC with a html viewer somewhere. But recycling such code would probably be more work than rewriting it.