I don't see how bloggers implement Markdown in their flow. If I create an entire blog in MD and convert to HTML, I'm just creating another page I can link to with from index.html. I could simply write a new HTML from scratch and do the same thing, which is arguably easier because if I write in MD and then convert, the conversion process adds all sorts of unneeded styles/IDs etc.
For example, if I create an H2 heading like this:
## This is Heading 2
The resulting HTML file will have this in its place:
<h2 id="This-is-heading-2">This is heading 2<h2>
Why do I want these IDs and other artifacts automatically inserted? Markdown seems pretty popular, so I trust there is a reason? What is the recommended process?
Related
This seems like it should be straightforward but I've been prowling the documentation and web and haven't found the answer.
I want to output HTML doc from Sphinx. Ideally I'd like to have three levels of "note" type highlighted text boxes. ReST defines several "admonitions": (http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions) but most of the Sphinx HTML themes include special formatting only for Note and Warning. (I am using one of the preinstalled themes, Classic.)
I have two questions:
1) How can I customize the color behind Warning in my documents?
2) How can I add a formatting style for Caution?
I see that these all end up with tags like <div class="admonition warning"> ... in the HTML output. But I can't find where the formatting for that class is defined. Is it in a stylesheet? Is it in a layout.html file or some other file?
Is there anything that explains how the various files in themes actually interact with each other? I haven't found a good primer. (I am no expert on css-based HTML either, so maybe that's part of the problem.)
Okay, I figured out more and have a working workaround. (I'm still not sure how I'm supposed to handle this.)
Looks like my HTML code is reading directly from a few cascading stylesheets stored along with the output in a directory called _static. There's classic.css, which inherits from basic.css.
I don't understand how these relate to the files named like basic.css_t that live in the Python Sphinx install.
To change things, should I (A) try altering the _t files? or (B) create an altered local copy of classic.css that lives in my source directory?
If I go with B, more questions.
Will it be overwritten by the values in the css_t template at build time? (I guess this is easy enough to test)
Is it good practice to use the same filename for a modified version of that stylesheet?
Here's a workaround that avoids those questions and seems to be doing what I want - from this: https://github.com/snide/sphinx_rtd_theme/issues/117
I created an override stylesheet that includes just the formatting I want to change.
I stored it in the _static of my source directory.
I defined it in my conf.py as follows:
html_context = {
'css_files': [
'_static/theme_overrides.css',
],
}
Now, that github discussion said that this wasn't a solution for all kinds of themes (including the RTD theme mentioned in the question) but I think I'm safe for now.
What more should I know?
I'm working on software creating annotations and would like my main data structure to be based around markdown.
I was thinking of working with an existing markdown editor, but hacking it so that certain tags, i.e. [annotation-id-001]Sample text.[/annotation-id-001] did not show up as rendered HTML; the above would output Sample text. in an HTML preview and link to a separate annotation with the ID 001.
My question is, is this the most efficient way to represent this kind of metadata inside of a markdown document? Also, if a user wants to legitimately use something like "[annotation-id-001]" as text inside of their document, I assume that I would have to make that string syntax illegal, correct?
I don't know what Markdown parser you use but you can abord your problem with different points of view:
first you can "hack" an existing parser to exclude your annotation tags from "classic" parsing and include them only in a certain mode
you can also use the internal "meta-data" information proposed by certain parsers (like MultiMarkdown or MarkdownExtended) and only write your annotations like meta-data with a reference to their final place in content
or, as mentionned by mb21, you can use simple links notation like [Sample text.](#annotation-id-001) or use footnotes like [Sample text.](^annotation-id-001) and put your annotations as footnotes.
I'd like to achieve the following and I'm looking for ideas. I have a document and I want to represent/transform this content in/to a nice SAPUI5 framework. My idea is the following: a split app with having the paragraph titles in the master view (plus a search function on top) and the respective content in the detail view.
I'd like to know from you if
a) you might want to share your ideas and hints on alternatives.
b) this can be achieved within one single file (i.e. all the code for the split app and document content in one html) and maybe using pure html code (xml also feasible) - against the background of easily handing a large amount of text available in html.
c) if you happen to have/know a reusable template.
Thanks in advance!
An interesting question. I went through a similar exercise once, re-presenting my site with UI5.
To your questions:
(a) I would think that the approach you suggest is a good one
(b) You can indeed include all the app in a single file, I do that often by using script templates, even with XML Views. You can see some examples in my sapui5bin repository, in particular in the SinglePageExamples folder. Have a look at this html file for example: https://github.com/qmacro/sapui5bin/blob/master/SinglePageExamples/SAP-Inside-Track-Sheffield-2014/end.html
What I would suggest is, rather than intermingle the document content and the app & view definitions, maintain the content of your document separately, for example, in XML or JSON, and use a client side model to load it in and bind the parts to the right places.
I am building an octopress blog. In that blog, a number of entries have footnotes. The markdown files currently denote a footnote like so:
"This is the main text <footnote>and this is the footnote</footnote> where
we speak of main-text things"
What I want to do is extract the footnotes from the body text and then have access to both the main text AND the footnotes as variables in the layout.
I've made some progress with this by creating a filter but it doesn't work very well because filters always output directly on return and I need to format the footnotes.
Would a generator be more appropriate? A converter? Should I not be using liquid tags at all in this case?
Filters make the most sense to me. Is there a way to get the return value of a filter without it printing to the screen? I currently use this:
{{ content | footnotes }}
But that just dumps the array as one big, unformatted array. If it isn't blindingly obvious already, I'm just getting started with Liquid and I'm a little confused.
Depending on your markdown parser you could just write the footnotes normally in the markdown. This is what I'm using on my blog. This is my config in the _config.yml file:
markdown: rdiscount
rdiscount:
extensions:
- autolink
- footnotes
- smart
Then I just use footnotes by using [^1] to specify the footnote and
[^1]: My footnote
To show it at the bottom of the screen.
Or are you trying to show footnotes at some other part of the screen and not at the bottom of the post?
I convert a book which is written in DocBook into a single page HTML. The HTML contains a TOC:
<div class="toc">
<dl>
<dt><span class="preface">Preface</span></dt>
<dt><span class="chapter"><a href="#installation-und-versionsauswahl">1. Version Selection and
Installation</a></span></dt>
[...]
I'd like to use kindlegen to convert the HTML into a file I can use with a Kindle. That works without a problem. BUT the TOC is not recognized as a TOC. The Kindle user can't access the TOC directly with the TOC button.
What do I have to change that kindlegen recognize the TOC in my HTML file?
I'd recommend reading the official Kindle publishing guidlines from Amazon.
AFAIK kindlegen can't do that, you need a proper NCX file or an OPF with properly set TOC setting.
See also this short tutorial.
In case useful, I knocked up a quick PHP script to generate very basic NCX and OPF files to support the TOC without having to break up the document. I wrote the script based on a MS Word documented saved as HTML (so it is hard coded to use those style names). Just noting it here in case useful to anyone who comes along this post in the future. http://alankent.me/2016/03/05/creating-a-kindle-book-using-microsoft-word-quick-note/