- Be the root directory for this Hugo site (the directory containing
config.toml). - Run
hugo server --port 1111 - See the site served on “http://localhost:1111/”.
M-x org-hugo-export-subtree-to-md.
This post has no date.
Export this second post only by bringing point here and doing M-x org-hugo-export-subtree-to-md.
To be fixed (Now fixed): The sub-headings in a post get exported as Heading 1
instead of Heading 2.
For example, this sub-section’s heading is exported as:
# Unclickable image
instead of
## Unclickable image
Solution: Above is fixed by setting HUGO_OFFSET_LEVEL to 1.
So the sub-heading title and the post title both get the Heading 1 tag and look the same size.
Click below image to jump to the unicorn image.
- NOTE
file:has to be used in both Link and Description components of the Org link.
Image with ATTR_HTML Issue # 17
If you link to files outside of the Hugo static directory, ensure
that the path contains /static/ if you would like to preserve the
directory structure.
Example translations between outside static directory paths to the
copied location inside static:
Outside static | Copied-to location inside static | Explanation |
|---|---|---|
~/temp/static/images/foo.png | <HUGO_BASE_DIR>/static/images/foo.png | If the outside path has /static/ in it, the directory structure after that is preserved when copied. |
~/temp/static/img/foo.png | <HUGO_BASE_DIR>/static/img/foo.png | (same as above) |
~/temp/static/foo.png | <HUGO_BASE_DIR>/static/foo.png | (same as above) |
~/temp/static/articles/zoo.pdf | <HUGO_BASE_DIR>/static/articles/zoo.pdf | (same as above) |
Outside static | Copied-to location inside static | Explanation |
|---|---|---|
~/temp/bar/baz/foo.png | <HUGO_BASE_DIR>/static/ox-hugo/foo.png | Here, as the outside path does not have /static/, the file is copied to the ox-hugo/ dir in Hugo static/ dir. |
- Note
- The
ox-hugosub-directory name is because of the default value oforg-hugo-default-static-subdirectory-for-externals.
Some more text, after image.
Hey! I have a link here (Awesome!)
title string of front matter do not
get escaped.. foo_bar must not become foo\_bar.
Testing a post with double quotes in the description.
This post must not be exported as it is tagged noexport.
First article.
This will land in content/articles/ as the parent of this subtree
sets EXPORT_HUGO_SECTION to articles. Note that the theme needs to
define at least the single.html, either in the layouts/_default/
directory, or layouts/articles/, either in the Hugo base dir or the
theme dir.
This will also land in content/articles/ the same way.
| h1 | h2 |
| a | b |
| c | d |
| 1 | 2 | 3 |
| a | b | e |
| c | d | f |
| 1 | 2 | 3 | 4 |
| a | b | e | g |
| c | d | f | h |
| 1 | 2 | 3 | 4 |
| a | b | e | g |
| c | d | f | h |
|---|
| 1 | 2 | 3 | 4 |
| a | b | e | g |
| c | d | f | h |
|---|
| 1 | 2 | 3 | 4 |
|---|---|---|---|
| a | b | e | g |
| c | d | f | h |
| 1 | 2 | 3 | 4 |
|---|---|---|---|
| a | b | e | g |
| c | d | f | h |
local.mk:
prefix- Org installation directory
prefix = /dir/where/you/want/to/install/org # Default: /usr/share
The
.elfiles will go to$(prefix)/emacs/site-lisp/orgby default. If you’d like to change that, you can tweak thelispdirvariable. infodir- Org Info installation directory. I like to keep the
Info file for development version of Org in a separate
directory.
infodir = $(prefix)/org/info # Default: $(prefix)/info
ORG_MAKE_DOC- Types of Org documentation you’d like to build by
default.
# Define below you only need info documentation, the default includes html and pdf ORG_MAKE_DOC = info pdf card # html
ORG_ADD_CONTRIB- Packages from the
contrib/directory that you’d like to build along with Org. Below are the ones on my must-have list.# Define if you want to include some (or all) files from contrib/lisp # just the filename please (no path prefix, no .el suffix), maybe with globbing # org-eldoc - Headline breadcrumb trail in minibuffer # ox-extra - Allow ignoring just the heading, but still export the body of those headings # org-mime - Convert org buffer to htmlized format for email ORG_ADD_CONTRIB = org-eldoc ox-extra org-mime
EXPORT_HUGO_CODE_FENCE property to t.
Note that to disable the code fence option, the value portion of the
property needs to be left empty instead of setting to nil!
:PROPERTIES: :EXPORT_HUGO_CODE_FENCE: :END:
prefix = /dir/where/you/want/to/install/org # Default: /usr/shareBelow is an example of such a case:
- List item 1
- List item 1.1 in code block - List item 1.2 in code block
- List item 2
+ List item 2.1 in code block + List item 2.2 in code block
- List item 3
- List item 1
*abc* /def/ =def=
- List item 2
- list 1str = 'a\tbc'
print(str[1:])bc
The whitespace before “bc” in the results block above should be preserved.
Test case for the case where user has setorg-hugo-langs-no-descr-in-code-fences to a list containing the
element org.
As this variable is dependent on user’s config, this post is not set to be exported by default.
The issue with Hugo will be seen if:
pygmentsCodeFences = trueis set in the Hugo siteconfig.toml,- a source block’s language is set to one that’s not supported by
Pygments (like org, and thus the below example with source code
language set to
org), and org-hugo-langs-no-descr-in-code-fencesis set to a value not containing that lanaguage descriptor (orgin this case).
# Org comment
Export this post after setting
=org-hugo-langs-no-descr-in-code-fences= to =(org)= and temporarily
removing the =noexport= tag.
Below table shows the translation of Org markup to Markdown markup in
the exported .md files.
| Org | Markdown | In Hugo rendered HTML |
|---|---|---|
*bold* | **bold** | bold |
/italics/ | _italics_ | italics |
| ==monospace== | `monospace` | monospace |
~key-binding~ | <kbd>key-binding</kbd> | key-binding |
- if org-hugo-use-code-for-kbd is non-nil [default] | ||
- Requires CSS to render the <kbd> tag as something special. | ||
~key-binding~ | `key-binding` | |
- if org-hugo-use-code-for-kbd is nil | ||
+strike-through+ | ~~strike-through~~ | |
_underline_ | <span class = "underline">underline</span> | underline |
- Requires CSS to render this underline class as an underline. |
~C-h f~ will show up as <kbd>C-h
f</kbd>.
Example:
- Few of Emacs help keybindings:
C-h f,C-h v
<kbd> tag generation by setting EXPORT_HUGO_USE_CODE_FOR_KBD
property to t. So ~C-h f~ will show up as <kbd>C-h f</kbd>.
Example:
- Few of Emacs help keybindings:
C-h f,C-h v
nil!
:PROPERTIES: :EXPORT_HUGO_USE_CODE_FOR_KBD: :END:
Here ~C-h f~ will show up as `C-h f` in Markdown and then
<code>C-h f</code> in the final Hugo generated HTML.
Example:
- Few of Emacs help keybindings:
C-h f,C-h v
*This is a sentence that should render completely in bold. It is broken across multiple lines (in Org source) because of auto-filling. But that should not break the bold rendering. But it does by default.*
If you do not see the above paragraph completely in bold, have below in your emacs config to fix it:
(with-eval-after-load 'org
;; Allow multiple line Org emphasis markup.
;; http://emacs.stackexchange.com/a/13828/115
(setcar (nthcdr 4 org-emphasis-regexp-components) 20) ;Up to 20 lines, default is just 1
;; Below is needed to apply the modified `org-emphasis-regexp-components'
;; settings from above.
(org-set-emph-re 'org-emphasis-regexp-components org-emphasis-regexp-components))This is an exampleFor this post, we should see just the menu weight and identifier properties get overridden.
You need to set unique menu identifiers, else you get a Hugo error like this:
ERROR 2017/07/18 12:32:14 Two or more menu items have the same name/identifier in Menu "main": "menu-meta-data-in-yaml-front-matter". Rename or set an unique identifier.For this post, we see that no menu properties are inherited from the parent; only the menu properties set in his subtree are effective. Testing the addition of menu meta data to the YAML front matter. Here the front matter format is set to YAML using the
HUGO_FRONT_MATTER_FORMAT key in property drawer.
Here there is white space in menu entry keyword.
Testing the addition of menu meta data to the YAML front matter. Here the front matter format is set to YAML using theHUGO_FRONT_MATTER_FORMAT key in property drawer.
Here there is white space in menu name property.
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :baz zoo :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :alpha 1 :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :beta “two words” :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :gamma 10From *(org) Property syntax*:It is also possible to add to the values of inherited properties. The following results in the ‘genres’ property having the value “Classic Baroque” under the ‘Goldberg Variations’ subtree.
* CD collection ** Classic :PROPERTIES: :GENRES: Classic :END: *** Goldberg Variations :PROPERTIES: :Title: Goldberg Variations :Composer: J.S. Bach :Artist: Glen Gould :Publisher: Deutsche Grammophon :NDisks: 1 :GENRES+: Baroque :END:Here is the summary.
Here is text after the summary splitter.
This underscore should appear escaped in Markdown: _This underscore is in a verbatim block, so it should not be escaped:
_
This underscore also shouldn’t be escaped as it’s in an emoji code: 🙌
And these ones should be eventually removed and underline the text (Requires CSS to do so.) – Org syntax.
- This is italics, and *this is bold too*, and back to plain italics.
- This is bold, and /this is italics too/, and back to plain bold.
| Rendered Actual | Rendered Expection | |
|---|---|---|
| 1 | ‘This’ | ‘This’ |
| 2 | “This” | “This” |
| 3 | “It’s” | “It’s” |
| 4 | ‘It’s’ | ‘It’s’ |
| 5 | ”http://localhost:1111/” | “http://localhost:1111/” |
| 6 | ”http://localhost:1111/”. | “http://localhost:1111/”. |
Note: There is a rendering issue is Row 5 above. That seems to be a corner case, because notice that Row 6 looks fine just because there was a trailing period. Will live with this issue for now.
The strings in these two columns should look the exact same.| Character | Rendered Actual | Rendered Expection | |
|---|---|---|---|
| 1 | Hyphen | a - b | a - b |
| 2 | Ndash | a – b | a – b |
| 3 | Mdash | a — b | a — b |
| 4 | Ellipsis | a … b | a … b |
This post has italics, monospace and bold in the title. This is to
test that those markup characters do not end up in the title front
matter of the post because HTML does not allow markup in the <title>
section.
So the title of this post should read as “ndash and mdash”.
This is some text[fn:1].Note to self: You *cannot* name an Org heading ‘Footnotes’; that’s reserved by Org to store all the footnotes.
This is some text[fn:2]. This is some text[fn:1][fn:2]. This is some text[fn:1]. This is some text[fn:1]. This is some text[fn:1]. This is some text[fn:3]. Testing tags set using Org tags in headings. The Org tags do not allow spaces. So the trick we use is replace double underscores with spaces.So an Org tag @abc__def becomes Hugo category abc def.
So an Org tag abc__def becomes Hugo tag abc def.
So an Org tag @abc__def becomes Hugo category abc def.
catA and tagged meow.
This gets both categories catA and catB.
Obviously, all the =CUSTOM_ID=’s set by the user in this file have to
be unique.
- Link to Heading 2
- Link to Heading 1
- Inline equations are wrapped between
\(and\).-
$wrapping also works, but it is not preferred as it comes with restrictions like “there should be no whitespace between the equation and the$delimiters”.So
$ a=b $will not work (it will look like: $ a=b $), but$a=b$will work (it will look like:$a=b$ ).On the other hand, both
\(a=b\)(it will look like: \(a=b\)) and\( a=b \)(it will look like: \( a=b \)) will work.
-
- One-per-line equations are wrapped between
\[and\]or$$delimiters.
For example, below in Org:
LaTeX formatted equation: \( E = -J \sum_{i=1}^N s_i s_{i+1} \)
will look like this in Hugo rendered HTML:
LaTeX formatted equation: \( E = -J ∑i=1^N s_i si+1 \)
(Don’t see this in Markdown, see what it looks after Hugo has processed it.)
Here’s another example, taken from (org) LaTeX fragments.
Below in Org:
If $a^2=b$ and \( b=2 \), then the solution must be either
$$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]
renders to:
If
(Note that the last two equations show up on their own lines.)
You need to force end of list when you have something like an unordered list immediately following an ordered list.The easiest and cleanest way to do that is adding a comment between those lists. – Reference
That would be the implementing in the Org exporter backend. But in Org, two consecutive blank lines after a list ends the list.
In the below example, the foo* items would be in a different <ul>
element than the bar* items.
- foo1
- foo2
- bar1
- bar2
- foo3
- foo4
- bar3
- bar4
- foo5
- foo6
- bar5
- bar6
- foo1
- foo2
- bar1
- description
- bar2
- description
- foo1
- foo2
- bar1
- bar2
- baz1
- baz2
- zoo1
- zoo2
- numbered1
- numbered2
- This will be 1.
- This will be 2.
- [@10] This will be 10!
- This will be 11.
- [@17] This will be 17!
- This will be 18.
- [@123] This will be 123!
- This will be 124.
- This will be 1 again.
- This will be 2.
Another example:
- This will be 1.
- [@3] This will be 3!
- [@7] This will be 7!
- [@100] This will be 100!
See (org) Plain lists to read more about plain lists in Org.
This is a check-list:Checklist showing progress in percentage.
- [ ] Task 1
- [X] Task 2
- [X] Task 3
- [ ] Task 4
- [X] Task 5
Checklist showing progress in ratio.
- [ ] Task 1
- [ ] Task 2
- [X] Task 3
- [ ] Task 4
- [X] Task 5
Quote 1. This is a long quote that auto-fills into multiple lines in Org, but it will be a single paragraph in the exported format.
Quote 2. This is a short quote.
Quote 3. This is a multi-paragraph quote.
This is the second paragraph.
Some other text.
To preserve the line breaks, indentation and blank lines in a region, but otherwise use normal formatting, you can use the verse construct, which can also be used to format poetry – Reference. Some text before indented text.Org removes indentation from the first line of the text block even in
a Verse block. To get around that, the trick is to use the >
character before the required indentation spaces only on the first
non-blank line in a Verse block. Only that first > character is
removed when translating to Markdown.
- More indentation than in the above example:
- Leading blank line followed by indented text:
- Indented text followed by a trailing blank line:
- Using tab characters for indentation; each tab character still
constitutes for one
in HTML.
Only the first > character immediately following spaces and empty
lines will be removed:
If someone really wants to have > as the first non-blank character
in the final output, they can use >> instead.. only for that first
instance. The below Verse block is same as above except that the
first > is retained in the final output.
Some text.
Some text.
Some text.
Some text.| /1 | /2 | /3 | /4 | /5 | /6 | /7 | /8 | /9 | /10 | /11 | /12 | /13 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1/1 | 1/3 | 1/5 | 1/6 | 1/7 | 1/8 | 1/9 | 1/10 | 1/11 | 1/12 | 1/13 | ||
| 2/1 | 2/2 | 2/3 | 2/4 | 2/5 | 2/6 | 2/7 | 2/8 | 2/9 | 2/10 | 2/11 | 2/12 | 2/13 |
| 3/1 | 3/2 | 3/3 | 3/5 | 3/6 | 3/7 | 3/8 | 3/9 | 3/10 | 3/11 | 3/12 | 3/13 | |
| 4/1 | 4/2 | 4/3 | 4/4 | 4/5 | 4/6 | 4/7 | 4/8 | 4/9 | 4/10 | 4/11 | 4/12 | 4/13 |
| 5/1 | 5/2 | 5/3 | 5/4 | 5/5 | 5/6 | 5/7 | 5/8 | 5/9 | 5/10 | 5/11 | 5/12 | 5/13 |
| 6/1 | 6/2 | 6/3 | 6/4 | 6/5 | 6/6 | 6/7 | 6/8 | 6/9 | 6/10 | 6/11 | 6/12 | 6/13 |
| 7/1 | 7/2 | 7/3 | 7/4 | 7/5 | 7/6 | 7/7 | 7/8 | 7/9 | 7/10 | 7/11 | 7/12 | 7/13 |
| 8/1 | 8/2 | 8/3 | 8/4 | 8/5 | 8/6 | 8/7 | 8/8 | 8/9 | 8/10 | 8/11 | 8/12 | 8/13 |
| 9/1 | 9/2 | 9/3 | 9/4 | 9/5 | 9/6 | 9/7 | 9/8 | 9/9 | 9/10 | 9/11 | 9/12 | 9/13 |
| 10/1 | 10/2 | 10/3 | 10/4 | 10/5 | 10/6 | 10/7 | 10/8 | 10/9 | 10/10 | 10/11 | 10/12 | 10/13 |
| 11/1 | 11/2 | 11/3 | 11/4 | 11/5 | 11/6 | 11/7 | 11/8 | 11/9 | 11/10 | 11/11 | 11/12 | 11/13 |
| 12/1 | 12/2 | 12/3 | 12/4 | 12/5 | 12/6 | 12/7 | 12/8 | 12/9 | 12/10 | 12/11 | 12/12 | 12/13 |
| 13/1 | 13/2 | 13/3 | 13/4 | 13/5 | 13/6 | 13/7 | 13/8 | 13/9 | 13/10 | 13/11 | 13/12 | 13/13 |
nil or false.
These will not be rendered as fractions:
But these will always be rendered as fractions, even when the
Blackfriday fractions option is set to false like in this post.
- 1/2, 1/4, 3/4
t or true.
All of these will be rendered as fractions:
Below are special as they will always be rendered as fractions, even
when the Blackfriday fractions option is set to false (though this
post has that option set to true – which is also the default value).
- 1/2, 1/4, 3/4
hardLineBreak extension is enabled here even where
user used the wrong case in the extension name:
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardlinebreak
instead of:
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardLineBreak
The Blackfriday extension names are case-sensitive. So even though,
the wrong case is used in the Org property drawer, ox-hugo ensures
that the Markdown front matter is written in the correct case!
a b c
Above, a, b and c must appear on separate lines.
a b cAbove, a, b and c must appear on separate lines.
a b cAbove, a, b and c must appear on separate lines.
:EXPORT_HUGO_BLACKFRIDAY+: :angledquotes t :hrefTargetBlank true :EXPORT_HUGO_BLACKFRIDAY+: :extensions tabsizeeight hardlinebreak :EXPORT_HUGO_BLACKFRIDAY+: :extensionsmask fencedcode strikethrough- Extensions enabled
tabSizeEight,hardLineBreak- Extensions disabled
fencedCode,strikethrough
“this”
a b c
Check the ID for all the headings in this post’s HTML. The ID’s will look something like:
<h2 id="plain-id-anchors-disabled:c94b2acd735ed6a466ef85be48bdea8c">Plain ID Anchors disabled</h2>where :c94b2acd735ed6a466ef85be48bdea8c is the document ID.
2/5
a–b c–d
Below, the code block language name will show up before the code.
(message "Hello")not-canceled
DONE state, a CLOSED
property is auto-inserted (default behavior).
If such a property is non-nil, the value (time-stamp) of that is used
to set the date field in the exported front-matter.
- Reference
- (org) Special properties or
C-h i g (org) Special properties
TODO keyword, the draft front matter variable
should be set to true.
Idea to to mark a post or blog idea as TODO that you yet have to
start writing.
DRAFT keyword too, the draft front matter variable
should be set to true.
Idea is to mark a post as DRAFT that you have already started
writing, or are in the process at the moment, but it is not yet ready
to be published
Fusce quam ligula, gravida ac dui venenatis, bibendum commodo lorem. Duis id elit turpis. Integer sed diam nibh. Donec tempus lacinia odio, a laoreet velit dictum id. Suspendisse efficitur euismod purus et porttitor. Aliquam sit amet tellus mauris. Mauris semper dignissim nibh, faucibus vestibulum purus varius quis. Suspendisse potenti. Cras at ligula sit amet nunc vehicula condimentum quis nec est. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Donec iaculis, neque sit amet maximus rhoncus, nisl tortor convallis ante, ut mollis purus augue ut justo. Praesent felis urna, volutpat sit amet posuere dictum, luctus quis nibh. Proin et tristique ipsum, in aliquam ante.
Aenean eget ex mauris. Cras ut tempor quam. Curabitur eget nulla laoreet, bibendum neque porta, tempus nulla. Ut tellus nisi, semper eu ligula pretium, aliquam accumsan dolor. Nunc fermentum cursus arcu eu suscipit. Nam dolor tellus, efficitur sed condimentum at, fringilla eget nisi. Nulla luctus metus felis. Suspendisse potenti. Cras lacinia orci nec dui sodales commodo. Donec tellus arcu, congue porta ultrices non, pretium et sapien. Proin mattis risus dignissim feugiat tristique. Donec nibh lorem, facilisis id posuere ut, varius ac urna. Etiam ultrices dignissim mauris, quis venenatis ex semper ut.
Curabitur id fermentum erat, rhoncus scelerisque est. Sed pulvinar, nulla sed sollicitudin scelerisque, ipsum erat sollicitudin dolor, ut commodo arcu justo vel libero. Curabitur turpis dolor, fermentum ut elit a, vehicula commodo nunc. Sed sit amet blandit nulla, quis sodales massa. Donec lobortis, urna vel volutpat ullamcorper, mauris est efficitur nulla, et suscipit velit dui at metus. Aliquam id sem sed metus tristique scelerisque nec vitae odio. Phasellus a pellentesque libero, vel convallis metus. Sed nec fringilla magna, non varius ex. Sed interdum eleifend ligula, quis porta enim ultrices a. Donec hendrerit diam ac elementum tincidunt.
Pellentesque eget nisl rhoncus, malesuada justo nec, suscipit quam. Nam sodales mauris eu bibendum suscipit. Vivamus sodales dui lorem, scelerisque pellentesque diam fermentum sed. Etiam fermentum nisl id nisl blandit, sit amet semper erat ultricies. Nulla tincidunt nulla metus, eu imperdiet lorem malesuada sagittis. Maecenas accumsan risus sed ante eleifend, vitae pretium leo porta. Suspendisse vitae eros vitae dui ornare condimentum id sit amet mauris. Etiam tincidunt consequat risus, eu posuere mi. Donec ut nunc eu massa porttitor suscipit nec nec neque. Suspendisse vitae tincidunt justo, sed molestie velit. Nullam pellentesque convallis ante, vel posuere libero blandit in.
[fn:3] This is a long footnote. It is so long that it gets auto-filled over multiple lines. But even then it should be handled fine.
[fn:2] Second footnote
[fn:1] First footnote