#+hugo_base_dir: ../

#+seq_todo: TODO DRAFT DONE
#+seq_todo: TEST__TODO | TEST__DONE

#+property: header-args :eval never-export

#+startup: indent

#+macro: doc [[https://ox-hugo.scripter.co/doc/$1][$2]]
#+macro: oxhugoissue =ox-hugo= Issue #[[https://github.com/kaushalmodi/ox-hugo/issues/$1][$1]]
#+macro: hugoissue =hugo= Issue #[[https://github.com/gohugoio/hugo/issues/$1][$1]]
#+macro: hugopr =hugo= PR #[[https://github.com/gohugoio/hugo/pull/$1][$1]]
#+macro: bfissue /Blackfriday/ Issue #[[https://github.com/russross/blackfriday/issues/$1][$1]]
#+macro: commit commit [[https://github.com/kaushalmodi/ox-hugo/commit/$1][$1]]

# https://scripter.co/latex-in-html/
#+macro: latex @@html:<span class="latex">L<sup>a</sup>T<sub>e</sub>X</span>@@
#+macro: youtube @@html:<div class="org-youtube"><iframe src="https://www.youtube-nocookie.com/embed/$1" allowfullscreen title="YouTube Video"></iframe></div>@@

#+author:

* Preparation
:PROPERTIES:
:EXPORT_FILE_NAME: prep
:EXPORT_DATE: 2017-07-12T17:05:38-04:00
:END:
1. Be the root directory for this Hugo site (the directory containing
   =config.toml=).
2. Run
  #+begin_example
  hugo server --port 1111
  #+end_example
3. See the site served on "http://localhost:1111/".
* Post 1
:PROPERTIES:
:EXPORT_FILE_NAME: post-1
:EXPORT_DATE: 2017-07-12T17:31:56-04:00
:END:
Export this *first* post only by bringing point here and doing =M-x org-hugo-export-wim-to-md=.
* Post 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-2
:END:
This post has no date.

Export this *second* post only by bringing point here and doing =M-x org-hugo-export-wim-to-md=.
* Image / Figure                                                      :image:
** Image links
:PROPERTIES:
:EXPORT_FILE_NAME: image-links
:EXPORT_DATE: 2017-07-15T07:49:44-04:00
:END:
This is some text before the first heading of this post.
*** Unclickable image (works!)

#+begin_src org
# Org source
,#+name: fig__unclickable_image
,#+caption: Don't click this image -- It's not a hyperlink
[[/images/org-mode-unicorn-logo.png]]
#+end_src

#+name: fig__unclickable_image
#+caption: Don't click this image -- It's not a hyperlink
[[/images/org-mode-unicorn-logo.png]]

-----
+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:
#+begin_example
# Unclickable image
#+end_example
instead of
#+begin_example
## Unclickable image
#+end_example

-----
*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.
*** Clickable link that opens the image (works!)
[[/images/org-mode-unicorn-logo.png][Click here to see the unicorn]]

Do *not* use ~file:~ prefix in the Description if you want the image
link to show up as-is i.e. not be replaced by the image-at-link like
in [[fig__clickable_image_that_opens_the_image]]:

#+begin_src org
# Org source
[[/images/org-mode-unicorn-logo.png][/images/org-mode-unicorn-logo.png]]
#+end_src

[[/images/org-mode-unicorn-logo.png][/images/org-mode-unicorn-logo.png]]

*** Clickable image that opens the image (works!)
Click below image to jump to the unicorn image.

#+begin_src org
# Org source
#+name: fig__clickable_image_that_opens_the_image
#+caption: Click this image -- It's a hyperlink
[[/images/org-mode-unicorn-logo.png][file:../files-to-be-copied-to-static/static/images/unicorn-logo-small.png]]
#+end_src

#+name: fig__clickable_image_that_opens_the_image
#+caption: Click this image -- It's a hyperlink
[[/images/org-mode-unicorn-logo.png][file:../files-to-be-copied-to-static/static/images/unicorn-logo-small.png]]

- NOTE :: =file:= has to be used in the *Description component* of the
          Org link.
**** Similar link with =#+name= specified
Here's a similar link with =#+name= specified.. which should also be
clickable.

#+name: fig__unicorn
[[/images/org-mode-unicorn-logo.png][file:/images/org-mode-unicorn-logo.png]]
**** Same link with =file:= in "link" portion of the Org link too
/Note that the =file:= is needed only in the "description" portion to
create a hyperlinked image that links to an image. But having =file:=
in the "link" portion of the Org link too shouldn't hurt./

Click below image to jump to the unicorn image.

[[file:/images/org-mode-unicorn-logo.png][file:/images/org-mode-unicorn-logo.png]]
*** Link to image outside of standard Hugo =static= directory
:PROPERTIES:
:CUSTOM_ID: path-containing-static
:END:
[[../files-to-be-copied-to-static/static/images/copy-of-unicorn-logo.png]]

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)                                                                                                      |
|----------------------------------+-------------------------------------------+----------------------------------------------------------------------------------------------------------------------|

The above path translations (when path contains =static=) hold true
even when inside page bundle pages.
**** Source path does not contain =/static/=
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]]
|--------------------------+------------------------------------------+-----------------------------------------------------------------------------------------------------------------------|
| 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-hugo= sub-directory name is because of the default
          value of
          =org-hugo-default-static-subdirectory-for-externals=.
***** Same image, but hyperlinked to itself
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png][file:../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]]
*** Link to an image with space in filename
This is a link to a file with a space in the filename:
{{{oxhugoissue(376)}}}
[[file:../files-to-be-copied-to-static/foo/unicorn logo.png][Link to ~unicorn logo.png~]]
** Inline hyperlinked and non-hyperlinked images                     :inline:
:PROPERTIES:
:EXPORT_FILE_NAME: inline-images
:END:
This tests the feature added to support proper export syntax for
inline images -- {{{oxhugoissue(125)}}}.
*** Inline non-hyperlinked image
**** No Alt text or any other attributes
This is an inline non-hyperlinked image without alt text or other
attributes: [[/images/org-mode-unicorn-logo.png]].
**** With Alt text
#+attr_html: :alt Inline Non-hyperlinked Image
This is an inline non-hyperlinked image with alt text:
[[/images/org-mode-unicorn-logo.png]].
**** With other HTML attributes
#+attr_html: :width 30
This is an inline non-hyperlinked image with the width attribute:
[[/images/org-mode-unicorn-logo.png]].
*** Non-inline non-hyperlinked image
[[/images/org-mode-unicorn-logo.png]]
*** Inline hyperlinked image
**** No Alt text or any other attributes
This is an inline non-hyperlinked image without alt text or other
attributes:
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png][file:../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]].
**** With Alt text
#+attr_html: :alt Inline Non-hyperlinked Image
This is an inline non-hyperlinked image with alt text:
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png][file:../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]].
**** With other HTML attributes
#+attr_html: :width 30
This is an inline non-hyperlinked image with the width attribute:
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png][file:../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]].
**** With space in the filename
This is an inline hyperlinked image with a space in the filename:
{{{oxhugoissue(277)}}}
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png][file:../files-to-be-copied-to-static/foo/unicorn%20logo.png]].

*** Non-inline hyperlinked image
 [[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png][file:../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]]
** Image captions
:PROPERTIES:
:EXPORT_DATE: 2017-07-19
:EXPORT_FILE_NAME: image-captions
:CUSTOM_ID: image-captions
:END:
#+begin_description
Figure captions with markup.
#+end_description

Some text before image.

#+caption: A unicorn! "Something in double quotes"
[[/images/org-mode-unicorn-logo.png]]

Some more text, after image.

#+caption: The /same/ figure *again*, testing [[https://ox-hugo.scripter.co][a link]] too!
[[/images/org-mode-unicorn-logo.png]]

** Image with Hugo =figure= shortcode parameters set using =ATTR_HTML=
:PROPERTIES:
:EXPORT_FILE_NAME: figure-shortcode-and-attr-html
:END:
{{{oxhugoissue(17)}}}
*** Setting =class= parameter
#+attr_html: :class inset
[[/images/org-mode-unicorn-logo.png]]

[[https://github.com/kaushalmodi/ox-hugo/issues/17#issuecomment-313627728][Discussion]]
**** COMMENT Below will not work!
You cannot wrap markdown code inside HTML.

As /rdwatters/ says [[https://discourse.gohugo.io/t/is-it-possible-to-insert-html-code-in-markdown-content/4867/4?u=kaushalmodi][here]],
#+begin_quote
HTML can be part of markdown because HTML-inside-markdown is part of
the spec. That said, remember that the spec disallows markdown nested
inside of HTML. So if you create a div, just make sure everything
inside that div is valid HTML.
#+end_quote

#+begin_export md
<div class="inset">
#+end_export
[[/images/org-mode-unicorn-logo.png]]
#+begin_export md
</div>
#+end_export
*** Setting =alt= parameter
[[https://www.reddit.com/r/emacs/comments/71wy6n/orgmode_as_a_markup_language_does_make_sense_even/dnhqudn/][Reference]]
#+attr_html: :alt Org-mode Unicorn Logo
[[/images/org-mode-unicorn-logo.png]]
*** Setting =title= parameter
#+attr_html: :title Logo
[[/images/org-mode-unicorn-logo.png]]
*** Setting image caption
The image caption can be set in two ways.
1. Using the Org =#+caption= keyword
2. Using =#+attr_html: :caption my caption=

The =#+caption= is available will get the higher precedence. In the
below image, caption is set using that:

#+include: "./all-posts.org::#image-captions" :only-contents t

Below, the same caption is set using the =#+attr_html= method instead:

Some text before image.

#+attr_html: :caption A unicorn!
[[/images/org-mode-unicorn-logo.png]]

/Enter a new line after the image link so that it's in an "Org
paragraph" that contains just that image. That tells Org that that
=#+attr_html= attribute is associated *only* with that image, and not
to the text that follows that image too./
*** Setting image size
**** Setting =:width= parameter
The image [[https://www.w3schools.com/tags/att_img_width.asp][width]] can be specified in *pixels* using the =:width=
parameter. *The height of the image will be resized proportionally.*

Below image is shown 50 pixels wide.
#+attr_html: :width 50
[[/images/org-mode-unicorn-logo.png]]

Below image is shown 100 pixels wide.
#+attr_html: :width 100
[[/images/org-mode-unicorn-logo.png]]

Below image is shown with a width of 1000 pixels! Now the size of this
image is 200px × 200px. But the image will still show up in 1000px ×
1000px size, but obviously heavily pixelated!

#+attr_html: :width 1000
[[/images/org-mode-unicorn-logo.png]]
**** Setting =:height= parameter
*NOTE*: Support for specifying =height= parameter to the Hugo =figure=
 shortcut was only added recently in [[https://github.com/gohugoio/hugo/pull/4018][hugo PR #4018]]. So setting this
 parameter will need *hugo v0.31* or later.

-----

The image [[https://www.w3schools.com/tags/att_img_height.asp][height]] can be specified in *pixels* using the =:height=
parameter. *The weight of the image will be resized proportionally.*

Below image is shown 50 pixels tall.
#+attr_html: :height 50
[[/images/org-mode-unicorn-logo.png]]

Below image is shown 100 pixels tall.
#+attr_html: :height 100
[[/images/org-mode-unicorn-logo.png]]

Below image is shown with a height of 1000 pixels! Now the size of
this image is 200px × 200px. But the image will still show up in
1000px × 1000px size, but obviously heavily pixelated!

#+attr_html: :height 1000
[[/images/org-mode-unicorn-logo.png]]
**** Setting both =:width= and =:height=
The *NOTE* above applies here too.. needs *hugo v0.31* or later.

The figure sizes below are intentionally set /mis-proportionally/ just
for testing.
- =:width 100 :height 200=
  #+attr_html: :width 100 :height 200
  [[/images/org-mode-unicorn-logo.png]]
- =:width 200 :height 100=
  #+attr_html: :width 200 :height 100
  [[/images/org-mode-unicorn-logo.png]]
*** Multiple =ATTR_HTML=
Below in Org source:
#+begin_src org
#+html: <style>.foo img { border:2px solid black; }</style>
#+attr_html: :alt Org mode logo
#+attr_html: :width 300 :class foo
[[https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png]]
#+end_src

Rendered this:

#+html: <style>.foo img { border:2px solid black; }</style>
#+attr_html: :alt Org mode logo
#+attr_html: :width 300 :class foo
[[https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png]]

*NOTE*: We cannot use =:style= in =#+attr_html= because Hugo does not
 /yet/ support a =style= argument in the =figure= shortcode [ [[https://github.com/gohugoio/hugo/blob/488631fe0abc3667355345c7eb98ba7a2204deb5/tpl/tplimpl/template_embedded.go#L22-L37][Source]]
 ].

So using =#+html: <style>.foo img ... </style>= and =#+attr_html: :class
 foo= as shown in the workaround above.
*** Other
Similarly, =:link=, =:attr=, =:attrlink= parameters in =#+attr_html=
are also supported to set the corresponding parameter in the Hugo
=figure= shortcode.
** Inlined SVG                                                   :svg:inline:
:PROPERTIES:
:EXPORT_FILE_NAME: inlined-svg
:END:
#+begin_description
Test inlined SVGs with hyperlinks.
#+end_description
{{{oxhugoissue(253)}}}

- [[http://plantuml.com/svg][Example of generating SVG with hyperlinks using PlantUML]]
- [[https://alligator.io/svg/hyperlinks-svg/][SVGs with hyperlinks need to be inlined]]

Introduce a new ~:inlined t~ HTML attribute.

#+begin_src plantuml :file images/svg-with-hyperlinks.svg :exports results
skinparam svgLinkTarget _parent
start
:[[https://ox-hugo.scripter.co/ ox-hugo homepage]];
stop
#+end_src
#+caption: An SVG with *hyperlinks* -- generated using PlantUML
#+attr_html: :inlined t
#+RESULTS:
[[file:images/svg-with-hyperlinks.svg]]
* Video                                                              :videos:
** Embedded Video                                                  :embedded:
:PROPERTIES:
:EXPORT_FILE_NAME: embedded-video
:END:
[[https://www.w3schools.com/html/html5_video.asp][Using ~video~ HTML5 tag]]

#+begin_export html
 <video width="320" height="240" controls>
  <source src="/videos/sample.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>
#+end_export
[[https://sample-videos.com/][Video source]]
* Setting heading anchors
:PROPERTIES:
:EXPORT_FILE_NAME: setting-heading-anchors
:EXPORT_DATE: 2017-07-12T17:05:39-04:00
:END:
** Heading 1 of the post
:PROPERTIES:
:CUSTOM_ID: cool-ref-1
:END:
Something
*** Heading 1.1 of the post
:PROPERTIES:
:CUSTOM_ID: cool-ref-1.1
:END:
Something else
** Heading 2 of the post
:PROPERTIES:
:CUSTOM_ID: cool-ref-2
:END:
Something 2
*** Heading 2.1 of the post
:PROPERTIES:
:CUSTOM_ID: cool-ref-2.1
:END:
Something 2.1
* Post heading with crazy characters
:PROPERTIES:
:EXPORT_FILE_NAME: post-heading-slugs
:EXPORT_DATE: 2017-07-12T13:46:33-04:00
:END:
** Releasing version 1.1
** Foo ( Bar ) Baz
** (Foo)Bar.Baz&Zoo
- ~.~ → ~dot~
- ~&~ → ~and~
** C++
- ~+~ → ~plus~
** Hey! I have a link [[https://example.org][here]] (Awesome!)
** Este título es en español
** Non-English titles
*** ÂÊÎÔÛ
*** ÁÉÍÓÚÝ
*** ÀÈÌÒÙ
*** ÄËÏÖÜ
*** ÃÐÑÕÞ
*** Ç
** Headings with HTML
*** Checklist [1/3]
Above title would render to ~Checklist <code>[1/3]</code>~ in
Markdown.
**** DONE Item 1
Above would render to ~<span class="todo DONE_">DONE </span> Item 1~
in Markdown.
**** TODO Item 2
Above would render to ~<span class="todo TODO_">TODO </span> Item 2~
in Markdown.
**** TODO Item 3
Above would render to ~<span class="todo TODO_">TODO </span> Item 3~
in Markdown.
*** Version 0.1 <2017-10-11 Wed>
Above title would render to ~Version 0.1 <span
class="timestamp-wrapper"><span class="timestamp">&lt;2017-10-11
Wed&gt;</span></span>~ in Markdown.
* Title in Front Matter                                               :title:
** Awesome title with "quoted text"
:PROPERTIES:
:EXPORT_FILE_NAME: post-title-quotes
:EXPORT_DATE: 2017-07-24
:END:
Testing a post with double quotes in the title.
** Under_scores_in_title
:PROPERTIES:
:EXPORT_FILE_NAME: under-scores-in-title
:EXPORT_DATE: 2017-07-28
:END:
Ensure that the underscores in =title= string of front matter do not
get escaped.. =foo_bar= must not become =foo\_bar=.
** Allow empty titles                                                 :empty:
:PROPERTIES:
:EXPORT_FILE_NAME: allow-empty-titles-2
:EXPORT_TITLE:
:END:
This post will be exported without =title= in the front-matter because
it is explicitly set to /empty/ using =:EXPORT_TITLE:=.
** En dash --, Em dash ---, Horizontal ellipsis ... in titles          :@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: en-dash-em-dash-hellip-in-titles
:END:
This tests an =ox-hugo= feature that gets around an upstream
limitation, where the Blackfriday /smartDashes/ rendering does not
happen in post titles ({{{hugoissue(4175)}}}).
** *Title with **lots** and *lots* of * aste*risks**
:PROPERTIES:
:EXPORT_FILE_NAME: title_with_asterisks
:END:
- All asterisk characters meant for Org =*bold*= markup are removed.
- The rest of the asterisk characters are retained.
** Title with /lots/ and lots / / / of forward/slashes
:PROPERTIES:
:EXPORT_FILE_NAME: title_with_forward_slashes
:END:
- All forward slash characters meant for Org =/italic/= markup are
  removed.
- The rest of the forward slash characters are retained.
** _Title_ with __lots and _lots_ _ _ of under_scores__
:PROPERTIES:
:EXPORT_FILE_NAME: title_with_under_scores
:END:
- All underscore characters meant for Org =_underline_= markup are
  removed.
- The rest of the underscore characters are retained.
** =Title with lots= of ` ` ` backticks` `foo =bar= ~ ~zoomba~
:PROPERTIES:
:EXPORT_FILE_NAME: title_with_backticks_equals_tildes
:END:
- All equal/tilde characters meant for Org =~code~= or ~=verbatim=~
  markup are removed.
- The rest of the equal/tilde characters are retained.
** =Title with lots= of ` ` ` backticks` * asterisks *bold*, /italics/ =retain*,_,` in monospace= underscores _ _ _*foo*_ =bar= **
:PROPERTIES:
:EXPORT_FILE_NAME: title_with_asterisks_underscores_backticks
:END:
- All the Org markup characters are removed.
- The "markup characters" not doing actual markup are retained.
** 2020-04-19
:PROPERTIES:
:EXPORT_FILE_NAME: title-with-just-date-chars
:END:
#+begin_description
Test the case where the title contains only the date, making it look
like a Hugo TOML date field.
#+end_description
{{{oxhugoissue(350)}}}
* Excluded post                                                    :noexport:
:PROPERTIES:
:EXPORT_FILE_NAME: excluded-post
:END:
This post must not be exported as it is tagged =noexport=.
* COMMENT Commented post
:PROPERTIES:
:EXPORT_FILE_NAME: commented-post
:END:
This post must not be exported as it is commented.
* Section                                                           :section:
** Articles
:PROPERTIES:
:EXPORT_HUGO_SECTION: articles
:END:
*** Article 1
:PROPERTIES:
:EXPORT_FILE_NAME: article-1
:EXPORT_DATE: 2017-07-19T08:34:29-04:00
:END:
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.
*** Article 2
:PROPERTIES:
:EXPORT_FILE_NAME: article-2
:EXPORT_DATE: 2017-07-19T08:34:22-04:00
:END:
Second article.

This will also land in =content/articles/= the same way.
** Emacs posts                                                        :emacs:
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
*** Emacs Post 1                                                        :foo:
:PROPERTIES:
:EXPORT_FILE_NAME: emacs-post-1
:EXPORT_DATE: 2017-07-12T17:31:56-04:00
:END:
Here is the first post on Emacs.
*** Emacs Post 2                                                        :bar:
:PROPERTIES:
:EXPORT_FILE_NAME: emacs-post-2
:EXPORT_DATE: 2017-07-12T17:31:56-04:00
:END:
Here is the second post on Emacs.
** HUGO_SECTION set in post subtree
:PROPERTIES:
:EXPORT_HUGO_SECTION: zoo
:EXPORT_FILE_NAME: post-in-zoo-section
:END:
#+begin_description
Test where ~EXPORT_HUGO_SECTION~ is set in the post subtree itself.
#+end_description
This post will be created in the =zoo= section.
** Null HUGO_SECTION                                             :root_level:
*** Using empty EXPORT_HUGO_SECTION
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: root-level-content-empty-section
:END:
#+begin_description
Case where ~EXPORT_HUGO_SECTION~ is set to nothing.
#+end_description

{{{oxhugoissue(164)}}}

This post is created at the site root.
*** Setting EXPORT_HUGO_SECTION to "/"
:PROPERTIES:
:EXPORT_HUGO_SECTION: /
:EXPORT_FILE_NAME: root-level-content-section-set-to-slash
:END:
#+begin_description
Case where ~EXPORT_HUGO_SECTION~ is set to ~/~.
#+end_description

{{{oxhugoissue(164)}}}

This behaves the same as *not setting* ~EXPORT_HUGO_SECTION~ at all.

This post is created at the site root.
** Section fragment concatenation       :fragment:concatenation:deep_nesting:
*** sub1 section
:PROPERTIES:
:EXPORT_HUGO_SECTION*: sub1
:END:
**** Post in sub1
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-section-frag-post-in-posts-sub1
:END:
#+begin_description
Test post created in ~posts/sub1~.
#+end_description
**** sub1/sub2 section
:PROPERTIES:
:EXPORT_HUGO_SECTION*: sub2
:END:
***** Post in sub1/sub2
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-section-frag-post-in-posts-sub1-sub2
:END:
#+begin_description
Test post created in ~posts/sub1/sub2~.
#+end_description
***** sub1/sub2/sub3 section
:PROPERTIES:
:EXPORT_HUGO_SECTION*: sub3
:END:
****** Post in sub1/sub2/sub3
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-section-frag-post-in-posts-sub1-sub2-sub3
:END:
#+begin_description
Test post created in ~posts/sub1/sub2/sub3~.
#+end_description
*** Post with all HUGO_SECTION, HUGO_SECTION*, EXPORT_FILE_NAME in same subtree
:PROPERTIES:
:EXPORT_HUGO_SECTION: articles
:EXPORT_HUGO_SECTION*: emacs
:EXPORT_FILE_NAME: hugo-section-frag-post-in-articles-emacs
:END:
#+begin_description
Test post created in ~articles/emacs~.
#+end_description
** Hugo Bundle concatenation :fragment:concatenation:deep_nesting:page_bundles:
:PROPERTIES:
:EXPORT_HUGO_SECTION: bundle-concat
:END:
*** Articles
:PROPERTIES:
:EXPORT_HUGO_SECTION*: articles
:END:
**** Articles Index page
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:END:
This is an index page (/branch/ bundle) for all the articles.

[[https://github.com/kaushalmodi/ox-hugo/issues/210#issuecomment-424891371][Ref]]
**** Article One
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: article-one
:END:
***** Article One Index page
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:END:
This is an index page (/branch/ bundle) for Articles/Article One.
***** Chapter One
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: chapter-one
:END:
****** Article One Chapter One Index page
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:END:
This is an index page (/branch/ bundle) for Articles/Article
One/Chapter One.
****** Section 1A
:PROPERTIES:
:EXPORT_FILE_NAME: section-1a
:END:
This is the content of Articles/Article One/Chapter One/Section 1A.
****** Section 1B
:PROPERTIES:
:EXPORT_FILE_NAME: section-1b
:END:
This is the content of Articles/Article One/Chapter One/Section 1B.
* Tables                                                              :table:
** Simple Table
:PROPERTIES:
:EXPORT_FILE_NAME: simple-table
:EXPORT_DATE: 2017-07-12T19:25:56-04:00
:END:
| h1 | h2 |
| a  | b  |
| c  | d  |
** Table with narrowest cols
:PROPERTIES:
:EXPORT_FILE_NAME: table-with-narrowest-columns
:EXPORT_DATE: 2017-07-12T19:26:00-04:00
:END:
| 1 | 2 | 3 |
| a | b | e |
| c | d | f |
** Table with top border
:PROPERTIES:
:EXPORT_FILE_NAME: table-top-border
:EXPORT_DATE: 2017-07-12T19:26:04-04:00
:END:
|---+---+---+---|
| 1 | 2 | 3 | 4 |
| a | b | e | g |
| c | d | f | h |
** Table with bottom border
:PROPERTIES:
:EXPORT_FILE_NAME: table-bottom-border
:EXPORT_DATE: 2017-07-12T19:26:06-04:00
:END:
| 1 | 2 | 3 | 4 |
| a | b | e | g |
| c | d | f | h |
|---+---+---+---|
** Table with top and bottom border
:PROPERTIES:
:EXPORT_FILE_NAME: table-top-and-bottom-border
:EXPORT_DATE: 2017-07-12T19:26:10-04:00
:END:
|---+---+---+---|
| 1 | 2 | 3 | 4 |
| a | b | e | g |
| c | d | f | h |
|---+---+---+---|
** Table with rule after first row
:PROPERTIES:
:EXPORT_FILE_NAME: table-only-rule-after-first-row
:EXPORT_DATE: 2017-07-12T19:26:13-04:00
:END:
| 1 | 2 | 3 | 4 |
|---+---+---+---|
| a | b | e | g |
| c | d | f | h |
** Table with borders and rule after first
:PROPERTIES:
:EXPORT_FILE_NAME: table-with-borders-and-rule-after-first
:EXPORT_DATE: 2017-07-12T19:26:16-04:00
:END:
|---+---+---+---|
| 1 | 2 | 3 | 4 |
|---+---+---+---|
| a | b | e | g |
| c | d | f | h |
|---+---+---+---|
** Table with single column
:PROPERTIES:
:EXPORT_FILE_NAME: table-with-single-column
:END:
| h1 |
| a  |
| b  |
** Table with single row
:PROPERTIES:
:EXPORT_FILE_NAME: table-with-single-row
:END:
| a | b |
** Table with single cell
:PROPERTIES:
:EXPORT_FILE_NAME: table-with-single-cell
:END:
| a |
** Table column alignment
:PROPERTIES:
:EXPORT_FILE_NAME: table-column-alignment
:END:
*** Table with 3 rows
|             <r> | <l>                  |           |              <c>              |
|           Right | Left                 | No        |            Center             |
| Long Content To | Spread Out the Width | Alignment | Of the Table To See Alignment |
|           Right | Left                 | Marker    |            Center             |
*** Table with 2 rows
| <l>  |         |  <c>   |   <r> |
| Left | Default | Center | Right |
| 1    |       2 |   3    |     4 |
*** Table with 1 row
/A table with just 1 row with alignment markers is as good as just
that row without the alignment markers. But hey, a test is a test./

| <l>  |         |  <c>   |   <r> |
| Left | Default | Center | Right |
*** Table with 0 rows!
/A table with zero rows, with just alignment markers, doesn't make
sense. But hey, a test is a test./

| <l> |   | <c> | <r> |

You should see *no* table exported above.
** Table name
:PROPERTIES:
:EXPORT_FILE_NAME: table-name
:END:
#+begin_description
Testing ~#+name~ and table.
#+end_description
#+name: tab__only_name
|-----+-----|
| h1  | h2  |
|-----+-----|
| abc | def |
|-----+-----|

#+name: tab__name_and_caption
#+caption: An Org table with both ~#+name~ and ~#+caption~
|-----+-----|
| h1  | h2  |
|-----+-----|
| abc | def |
|-----+-----|
** Table caption                                                    :caption:
:PROPERTIES:
:EXPORT_FILE_NAME: table-caption
:END:
The caption can contain be emphasized using the usual markup
characters too.

#+caption: Awesome table
| h1  | h2  | h3  |
|-----+-----+-----|
| abc | def | ghi |

Some text.

#+caption: /Another/ *awesome* table with [[https://ox-hugo.scripter.co][a link]]
| h1  | h2  | h3  |
|-----+-----+-----|
| jkl | mno | pqr |

Some more text.

#+caption: _Third_ table --- Caption with em-dash -- and -- en-dash
| h1  | h2  | h3 |
|-----+-----+----|
| stu | vwx | yz |
** Table Styling with ATTR_HTML and ATTR_CSS :attr___html:attr___css:css:@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: table-styling
:END:

This /table styling/ feature overcomes a known _limitation_ in
Hugo/Blackfriday ({{{bfissue(404)}}}) that doesn't allow wrapping
Markdown elements with =<div>= tags (so that a user can assign
classes, etc. to those =div= blocks).

So this feature had to be implemented at the expense of a nasty hack
demonstrated [[https://github.com/kaushalmodi/ox-hugo/issues/93#issue-270108567][here]].

-----

HTML5 does not allow =align=, =width=, etc. attributes *within* the
=table= tag [ [[https://www.w3.org/TR/2011/WD-html-markup-20110113/table.html#table-constraints][Ref]] ]. So instead =ox-hugo= simply wraps the table with
a =div= with a =class=. The table can then be customized using CSS,
either via the =#+attr_css= attribute above the tables, or by putting
verbatim CSS in =#+begin_export html= blocks. See below examples.
*** Table with only the class specified
#+attr_html: :class my-table
| h1  | h2  | h3  |
|-----+-----+-----|
| abc | def | ghi |

Above table is wrapped in a =my-table= class. Just doing that won't
bring any presentation changes to the table.. you'd need to add some
CSS that customizes =.my-table table=.
*** Table with only a CSS attribute specified
#+attr_css: :width 50%
| h1  | h2  | h3  |
|-----+-----+-----|
| abc | def | ghi |

Above table get wrapped in the auto-generated class
=table-nocaption=. The specified CSS attribute is auto-set for
=.table-nocaption table=.
*** Table with both class and CSS attribute specified
#+attr_html: :class my-table-2
#+attr_css: :width 80%
| h1  | h2  | h3  |
|-----+-----+-----|
| abc | def | ghi |

Above table get wrapped in the specified class =my-table-2=. The
specified CSS attribute is auto-set for =.my-table-2 table=.
*** Table with caption, and CSS attributes specified
#+caption: Table with caption, with left-aligned text
#+attr_css: :text-align left
| h1       | h2       | h3       |
|----------+----------+----------|
| abcdefgh | ijklmnop | qrstuvwx |

Above table get wrapped in the auto-generated class =table-1= (/"1",
because this is the first table with a caption on this page./). The
specified CSS attribute is auto-set for =.table-1 table=.

#+caption: Table with caption, with right-aligned text
#+attr_css: :text-align right
| h1       | h2       | h3       |
|----------+----------+----------|
| abcdefgh | ijklmnop | qrstuvwx |

#+caption: Table with caption, with center-aligned text
#+attr_css: :text-align center
| h1       | h2       | h3       |
|----------+----------+----------|
| abcdefgh | ijklmnop | qrstuvwx |
*** Table with caption, and both class and CSS attributes specified
#+caption: Table with caption, class and CSS attributes specified
#+attr_html: :class my-red-bordered-table
#+attr_css: :border 2px solid red
| h1  | h2  | h3  |
|-----+-----+-----|
| abc | def | ghi |

Above table get wrapped in the specified class
=my-red-bordered-table=. The specified CSS attribute is auto-set for
=.my-red-bordered-table table=.

Here's another table with the exact same class as that of the above
table. So the CSS properties do not need to be specified again.

Below table will also show up with a red border.

#+attr_html: :class my-red-bordered-table
| h1  | h2  | h3  |
|-----+-----+-----|
| jkl | kmo | pqr |
*** Table with verbatim CSS
There could be times when the CSS couldn't be simply specified using
the =#+attr_css= attribute. In those cases, simply set the table class
using =#+attr_html=, and put the CSS in the =#+begin_export html=
block.
#+begin_export html
<style>
.tab4 th,
.tab4 td {
    padding: 20px;
    text-align: left;
}
</style>
#+end_export
#+caption: Table with verbatim CSS
#+attr_html: :class tab4
| h1  | h2  | h3  |
|-----+-----+-----|
| abc | def | ghi |
*** More table styling examples
[[https://css-tricks.com/complete-guide-table-element/][Source: /css-tricks.com/]]
**** CSS-tricks Example Tables                                     :noexport:
***** Example Table 1
:PROPERTIES:
:CUSTOM_ID: css-tricks-example-table-1
:END:
| Name |    ID | Favorite Color |
|------+-------+----------------|
| Jim  | 00001 | Blue           |
| Sue  | 00002 | Red            |
| Barb | 00003 | Green          |
***** Example Table 2
:PROPERTIES:
:CUSTOM_ID: css-tricks-example-table-2
:END:
| 1 |  2 |  3 |  4 |  5 |
|---+----+----+----+----|
| 2 |  4 |  6 |  8 | 10 |
| 3 |  6 |  9 | 12 | 15 |
| 4 |  8 | 12 | 16 | 20 |
| 5 | 10 | 15 | 20 | 25 |
***** Example Table 3
:PROPERTIES:
:CUSTOM_ID: css-tricks-example-table-3
:END:
| Last Name | First Name | Email                 | Due     | Web Site                 |
|-----------+------------+-----------------------+---------+--------------------------|
| Smith     | John       | jsmith@gmail.com      | $50.00  | http://www.jsmith.com    |
| Bach      | Frank      | fbach@yahoo.com       | $50.00  | http://www.frank.com     |
| Doe       | Jason      | jdoe@hotmail.com      | $100.00 | http://www.jdoe.com      |
| Conway    | Tim        | tconway@earthlink.net | $50.00  | http://www.timconway.com |
**** Basic styling
***** Uncollapsed borders
#+begin_export html
<style>
.basic-styling td,
.basic-styling th {
  border: 1px solid #999;
  padding: 0.5rem;
}
</style>
#+end_export
#+attr_html: :class basic-styling
#+caption: Table with uncollapsed borders
#+include: "./all-posts.org::#css-tricks-example-table-1" :only-contents t
***** Collapsed borders
#+begin_export html
<style>
.collapsed table {
  border-collapse: collapse;
}
</style>
#+end_export
#+attr_html: :class collapsed basic-styling
#+caption: Table with collapsed borders
#+include: "./all-posts.org::#css-tricks-example-table-1" :only-contents t
**** Two Axis Tables
#+begin_export html
<style>
.two-axis-table td,
.two-axis-table th {
  width: 4rem;
  height: 2rem;
  border: 1px solid #ccc;
  text-align: center;
}
.two-axis-table th,
.two-axis-table td:nth-child(1) {
  background: lightblue;
  border-color: white;
  font-weight: bold;
}
.two-axis-table body {
  padding: 1rem;
}
</style>
#+end_export
#+attr_html: :class two-axis-table
#+caption: Table with 1st row and 1st column highlighted
#+include: "./all-posts.org::#css-tricks-example-table-2" :only-contents t
**** Sane Table
[[https://css-tricks.com/complete-guide-table-element/#article-header-id-17][Ref]]
#+begin_export html
<style>
.sane-table table {
  border-collapse: collapse;
  width: 100%;
}
.sane-table th,
.sane-table td {
  padding: 0.25rem;
  text-align: left;
  border: 1px solid #ccc;
}
</style>
#+end_export
#+attr_html: :class sane-table
#+caption: Sane Table --- with minimal styling
#+include: "./all-posts.org::#css-tricks-example-table-1" :only-contents t
**** Zebra Striping
#+begin_export html
<style>
.zebra-striping tbody tr:nth-child(odd) {
  background: #eee;
}
</style>
#+end_export
#+attr_html: :class zebra-striping sane-table
#+caption: Table with zebra striping
#+include: "./all-posts.org::#css-tricks-example-table-3" :only-contents t
**** Highlighting on Hover
***** Highlight Cell
#+begin_export html
<style>
.hl-table-cell td:hover { /* th:hover also if you wish */
  background: yellow;
}
</style>
#+end_export
#+attr_html: :class hl-table-cell sane-table
#+caption: Table where the hovered-upon cell highlights
#+include: "./all-posts.org::#css-tricks-example-table-3" :only-contents t
***** Highlight Row
#+begin_export html
<style>
.hl-table-row tbody tr:hover {
  background: yellow;
}
</style>
#+end_export
#+attr_html: :class hl-table-row sane-table
#+caption: Table where the hovered-upon row highlights
#+include: "./all-posts.org::#css-tricks-example-table-3" :only-contents t
**** Blur non-hovered Rows
/Let's-go-ballistic-with-CSS/ Edition :smile:
#+begin_export html
<style>
.blur-non-hovered body {
  background: #fafafa;
  color: #444;
  font: 100%/30px 'Helvetica Neue', helvetica, arial, sans-serif;
  text-shadow: 0 1px 0 #fff;
}

.blur-non-hovered strong {
  font-weight: bold;
}

.blur-non-hovered em {
  font-style: italic;
}

.blur-non-hovered table {
  background: #f5f5f5;
  border-collapse: separate;
  box-shadow: inset 0 1px 0 #fff;
  font-size: 12px;
  line-height: 24px;
  margin: 30px auto;
  text-align: left;
  width: 800px;
}

.blur-non-hovered th {
  background: linear-gradient(#777, #444);
  border-left: 1px solid #555;
  border-right: 1px solid #777;
  border-top: 1px solid #555;
  border-bottom: 1px solid #333;
  box-shadow: inset 0 1px 0 #999;
  color: #fff;
  font-weight: bold;
  padding: 10px 15px;
  position: relative;
  text-shadow: 0 1px 0 #000;
}

.blur-non-hovered th:after {
  background: linear-gradient(rgba(255,255,255,0), rgba(255,255,255,.08));
  content: '';
  display: block;
  height: 25%;
  left: 0;
  margin: 1px 0 0 0;
  position: absolute;
  top: 25%;
  width: 100%;
}

.blur-non-hovered th:first-child {
  border-left: 1px solid #777;
  box-shadow: inset 1px 1px 0 #999;
}

.blur-non-hovered th:last-child {
  box-shadow: inset -1px 1px 0 #999;
}

.blur-non-hovered td {
  border-right: 1px solid #fff;
  border-left: 1px solid #e8e8e8;
  border-top: 1px solid #fff;
  border-bottom: 1px solid #e8e8e8;
  padding: 10px 15px;
  position: relative;
  transition: all 300ms;
}

.blur-non-hovered td:first-child {
  box-shadow: inset 1px 0 0 #fff;
}

.blur-non-hovered td:last-child {
  border-right: 1px solid #e8e8e8;
  box-shadow: inset -1px 0 0 #fff;
}

.blur-non-hovered tr:nth-child(odd) td {
  background: #f1f1f1;
}

.blur-non-hovered tr:last-of-type td {
  box-shadow: inset 0 -1px 0 #fff;
}

.blur-non-hovered tr:last-of-type td:first-child {
  box-shadow: inset 1px -1px 0 #fff;
}

.blur-non-hovered tr:last-of-type td:last-child {
  box-shadow: inset -1px -1px 0 #fff;
}

.blur-non-hovered tbody:hover td {
  color: transparent;
  text-shadow: 0 0 3px #aaa;
}

.blur-non-hovered tbody:hover tr:hover td {
  color: #444;
  text-shadow: 0 1px 0 #fff;
}
</style>
#+end_export
#+attr_html: :class blur-non-hovered
#+caption: Table where rows except the hovered-upon get blurred
#+include: "./all-posts.org::#css-tricks-example-table-3" :only-contents t
** Table with Column Groups                 :wishlist:column_groups:noexport:
:PROPERTIES:
:EXPORT_FILE_NAME: table-column-groups
:END:
https://orgmode.org/manual/Column-groups.html

Looks like the only way to implement this is to export tables with
column groups in raw HTML -- <2018-01-07 Sun>.

| N | N^2 | N^3 | N^4 | ~sqrt(n)~ | ~sqrt[4](N)~ |
|---+-----+-----+-----+-----------+--------------|
| / |   < |     |   > |         < |            > |
| 1 |   1 |   1 |   1 |         1 |            1 |
| 2 |   4 |   8 |  16 |    1.4142 |       1.1892 |
| 3 |   9 |  27 |  81 |    1.7321 |       1.3161 |
|---+-----+-----+-----+-----------+--------------|
#+tblfm: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
* Source blocks                                                   :src_block:
** Code fence                                                    :code_fence:
*** Code-fenced source blocks (default behavior)
:PROPERTIES:
:EXPORT_FILE_NAME: code-fenced-src-blocks-default
:EXPORT_DATE: 2017-07-31
:END:
The source blocks are code-fenced by default.

#+include: "./all-posts.org::#example-text-with-code-blocks" :only-contents t
-----
*It is necessary to set the Hugo site config variable
=pygmentsCodeFences= to =true= for syntax highlighting to work for
fenced code blocks.*
*** Code-fenced source blocks
:PROPERTIES:
:EXPORT_HUGO_CODE_FENCE: t
:EXPORT_FILE_NAME: code-fenced-src-blocks
:EXPORT_DATE: 2017-07-13T17:49:22-04:00
:END:
Here the source blocks are explicitly set to be code-fenced by setting
the =EXPORT_HUGO_CODE_FENCE= property to =t=.

#+include: "./all-posts.org::#example-text-with-code-blocks" :only-contents t
-----
*It is necessary to set the Hugo site config variable
=pygmentsCodeFences= to =true= for syntax highlighting to work for
fenced code blocks.*
*** Code-fenced source blocks with backticks                      :backticks:
:PROPERTIES:
:EXPORT_HUGO_CODE_FENCE: t
:EXPORT_FILE_NAME: code-fenced-src-blocks-with-backticks
:END:
This code block contains a fenced code block with 4 backticks:
#+begin_src md
````emacs-lisp
(message "Hello")
````
#+end_src

This code block contains a fenced code block with 3 backticks:
#+begin_src md
```emacs-lisp
(message "Hello again")
```
#+end_src

This code block contains no backticks:
#+begin_src emacs-lisp
(message "Hello again x2")
#+end_src

This code block again contains a fenced code block with 4 backticks:
#+begin_src md
````emacs-lisp
(message "Hello again x3")
````
#+end_src

This code block contains a fenced code block with 6 backticks:
#+begin_src md
``````emacs-lisp
(message "Hello again x4")
``````
#+end_src

This code block again contains a fenced code block with 3 backticks:
#+begin_src md
```emacs-lisp
(message "Hello again x5")
```
#+end_src

This code block once again contains no backticks:
#+begin_src emacs-lisp
(message "Hello again x6")
#+end_src
** Highlight Shortcode                                  :highlight:shortcode:
*** Source blocks with =highlight= shortcode
:PROPERTIES:
:EXPORT_HUGO_CODE_FENCE:
:EXPORT_FILE_NAME: highlight-shortcode-src-blocks
:EXPORT_DATE: 2017-07-31
:END:
Note that to disable the code fence option, the value portion of the
property needs to be left *empty* instead of setting to =nil=!
#+begin_example
:PROPERTIES:
:EXPORT_HUGO_CODE_FENCE:
:END:
#+end_example
#+include: "./all-posts.org::#example-text-with-code-blocks" :only-contents t
*** Source blocks with line number annotation
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-with-line-numbers
:END:
- [[https://orgmode.org/manual/Literal-examples.html][Org reference]]
- [[https://gohugo.io/content-management/syntax-highlighting/][Hugo =highlight= shortcode with line numbers]]
**** Cases
:PROPERTIES:
:CUSTOM_ID: source-block-line-number-cases
:END:
***** Default new line number start
****** Org source
#+begin_src org :noweb yes
<<src-block-n-default-start>>
#+end_src
****** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-n-default-start>>
#+end_src
***** Specify new line number start
****** Org source
#+begin_src org :noweb yes
<<src-block-n-custom-start>>
#+end_src
****** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-n-custom-start>>
#+end_src
***** Default continued line numbers
****** Org source
#+begin_src org :noweb yes
<<src-block-n-default-continue>>
#+end_src
****** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-n-default-continue>>
#+end_src
***** Specify continued line numbers jump
****** Org source
#+begin_src org :noweb yes
<<src-block-n-custom-continue>>
#+end_src
****** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-n-custom-continue>>
#+end_src
*** Source blocks with highlighting
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-with-highlighting
:CUSTOM_ID: source-blocks-with-highlighting
:END:
**** Without line numbers
:PROPERTIES:
:CUSTOM_ID: source-blocks-with-highlighting-no-linenums
:END:
****** Org source
#+begin_src org :noweb yes
<<src-block-hl-without-n>>
#+end_src
****** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-hl-without-n>>
#+end_src
Above highlighting might look weird as the highlighting spans the full
page/container width. This could be either called a bug in Hugo, or
the HTML limitation.

A workaround is below.. *use line numbers too!*.
****** Highlighting only 1 line
******* Org source
#+begin_src org :noweb yes
<<src-block-hl-without-n-just-1-line>>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-hl-without-n-just-1-line>>
#+end_src
**** With line numbers *not* starting from 1
:PROPERTIES:
:CUSTOM_ID: source-blocks-with-highlighting-with-linenums-not-starting-from-1
:END:
With line numbers enabled, the highlighting is limited to the width of
the HTML table rows (because =ox-hugo= sets the =linenos=table= option
in the =highlight= shortcode when line numbers are enabled).

- Note 1 :: When using both, switches (like =-n=), and header args
            (like =:hl_lines=), the _switches have to come first_.
- Note 2 :: The line numbers in the value for =:hl_lines= parameter is
            always with the starting line number reference of 1. That
            has no relation with the value of the line numbers
            displayed using the =-n= or =+n= switches!
****** Org source
#+begin_src org :noweb yes
<<src-block-hl-with-n-not-1>>
#+end_src
****** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-hl-with-n-not-1>>
#+end_src
**** With line numbers
:PROPERTIES:
:CUSTOM_ID: source-blocks-with-highlighting-with-linenums
:END:
****** Org source
#+begin_src org :noweb yes
<<src-block-hl-with-n>>
#+end_src
****** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<<src-block-hl-with-n>>
#+end_src
** Source block with caption                                        :caption:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-caption
:END:
#+caption: Prefix value in =local.mk=
#+begin_src makefile
prefix = /dir/where/you/want/to/install/org # Default: /usr/share
#+end_src

#+caption: Hello --- Caption with em-dash -- and -- en-dash
#+begin_src emacs-lisp
(message "hello")
#+end_src
** Source and example blocks with list syntax in a list
*** Source blocks                                    :src_block:lists:hyphen:
**** Source block with list syntax in a list          :@upstream:blackfriday:
:PROPERTIES:
:EXPORT_DATE: 2017-08-01
:EXPORT_FILE_NAME: list-has-src-block-with-list-syntax
:END:
An upstream bug in {{{bfissue(239)}}} caused fenced code blocks in
lists to not render correctly if they contain Markdown syntax
lists. =ox-hugo= provides a hack to get around that bug.

Below is an example of such a case:

- List item 1
  #+begin_src md
  - List item 1.1 in code block
  - List item 1.2 in code block
  #+end_src
- List item 2
  #+begin_src md
  + List item 2.1 in code block
  + List item 2.2 in code block
  #+end_src
- List item 3

Another such example, but with space before a hyphen in source block:

1. First item
   #+begin_src yaml
   ports:
     foo: bar
   #+end_src
2. Second item
   #+begin_src yaml
   ports:
    - port: 80
   #+end_src
3. Third item
**** Source block without list syntax in a list
:PROPERTIES:
:EXPORT_DATE: 2017-08-01
:EXPORT_FILE_NAME: list-has-src-block-but-no-list-syntax
:END:
This case is not affected by /Blackfriday/ [[https://github.com/russross/blackfriday/issues/239][Issue #239]] as the fenced
code block does not have Markdown syntax lists.
- List item 1
  #+begin_src md
  ,*abc*
  /def/
  =def=
  #+end_src
- List item 2
**** Source block with list syntax but not in a list
:PROPERTIES:
:EXPORT_DATE: 2017-08-01
:EXPORT_FILE_NAME: src-block-outside-list-with-list-syntax
:END:
#+begin_src md
- list 1
#+end_src
*** Example blocks                               :lists:hyphen:example_block:
**** Example block with list syntax in a list         :@upstream:blackfriday:
:PROPERTIES:
:EXPORT_FILE_NAME: list-has-example-block-with-list-syntax
:END:
An upstream bug in {{{bfissue(239)}}} caused fenced code blocks in
lists to not render correctly if they contain Markdown syntax
lists. =ox-hugo= provides a hack to get around that bug.

Below is an example of such a case:

- List item 1
  #+begin_example
  - List item 1.1 in code block
  - List item 1.2 in code block
  #+end_example
- List item 2
  #+begin_example
  + List item 2.1 in code block
  + List item 2.2 in code block
  #+end_example
- List item 3

Another such example, but with spaces before the hyphens in example
blocks:

- List item 1
  #+begin_example
   - List item 1.1 in code block
   - List item 1.2 in code block
  #+end_example
- List item 2
  #+begin_example
    + List item 2.1 in code block
    + List item 2.2 in code block
  #+end_example
- List item 3
** Org Babel Results    :babel:results:indentation:example_block:fixed_block:
:PROPERTIES:
:EXPORT_FILE_NAME: org-babel-results
:END:
#+begin_description
Testing the export of Org Babel ~#+results:~ blocks with and without
wrapping with HTML attributes.
#+end_description
*** "Fixed block" Results block
Below also tests that the indentation in *results* blocks is
preserved.

#+begin_src python :exports both :results output
str = 'a\tbc'
print(str[1:])
#+end_src

#+results:
: 	bc

The whitespace before "bc" in the results block above should be
preserved.
**** "Fixed block" Results block with ~#+attr_html~
#+begin_src python :exports both :results output
str = 'd\tef'
print(str[1:])
#+end_src

#+attr_html: :class results-fixed-block
#+attr_css: :color blue
#+results:
: 	ef

Above results block will be in _blue_ text.
*** "Example block" Results block
#+begin_src nim :exports both :results output
echo "abc\ndef\nghi\njkl\nmno\npqr\nstu\nvwx\nyz0\n123\n456\n789"
#+end_src

#+results:
#+begin_example
abc
def
ghi
jkl
mno
pqr
stu
vwx
yz0
123
456
789
#+end_example
**** "Example block" Results block with ~#+attr_html~
#+begin_src nim :exports both :results output
echo "ABC\nDEF\nGHI\nJKL\nMNO\nPQR\nSTU\nVWX\nYZ0\n123\n456\n789"
#+end_src

#+attr_html: :class results-example-block
#+attr_css: :color green
#+results:
#+begin_example
ABC
DEF
GHI
JKL
MNO
PQR
STU
VWX
YZ0
123
456
789
#+end_example

Above results block will be in _green_ text.
** Indented source block :indented:lists:code_fence:highlight:src_block:@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-indented
:END:
#+begin_description
Test that indented source blocks, and also the ones in lists export
fine.
#+end_description

Some content.

#+begin_src emacs-lisp
(defun small-shell ()
  (interactive)
  (split-window-vertically)
  (other-window 1)
  (shrink-window (- (window-height) 12))
  (ansi-term))
#+end_src
*** Code blocks in list using code fences
Reference: {{{hugoissue(4006)}}}

- List item 1
  #+begin_src emacs-lisp
  (message "I am in list at level-1 indentation")
  #+end_src
  - List item 1.1
    #+begin_src emacs-lisp
    (message "I am in list at level-2 indentation")
    #+end_src
    - List item 1.1.1
      #+begin_src emacs-lisp
      (message "I am in list at level-3 indentation")
      #+end_src
  - List item 2.1
    #+begin_src emacs-lisp
    (message "I am in list back at level-2 indentation")
    #+end_src
- List item 2
  #+begin_src emacs-lisp
  (message "I am in list back at level-1 indentation")
  #+end_src

#+begin_src emacs-lisp
(message "And now I am at level-0 indentation")
#+end_src
*** Code blocks in list using ~highlight~ shortcode
Reference: {{{hugoissue(4717)}}}, {{{oxhugoissue(161)}}}

This is an *upstream* bug in ~hugo~ as of 2018-05-12. The issues is
that when the code blocks in ~highlight~ shortcodes are inserted at
the required indentation levels in lists.. so that they get rendered
*in* the list at *that* indentation level, those indentations are not
removed by ~hugo~, and thus become part of those code blocks.

Also, related to this issue, it can be seen that all such indented
code blocks have an empty second line too, probably just due to the
unremoved indentation on the last line of those code blocks.

In the above section, the same code blocks are code-fenced instead of
using ~highlight~ shortcode, and the extra indentation is not seen
there.

- List item 1
  #+begin_src emacs-lisp -n
  (message "I am in list at level-1 indentation")
  #+end_src
  - List item 1.1
    #+begin_src emacs-lisp -n
    (message "I am in list at level-2 indentation")
    #+end_src
    - List item 1.1.1
      #+begin_src emacs-lisp -n
      (message "I am in list at level-3 indentation")
      #+end_src
  - List item 2.1
    #+begin_src emacs-lisp -n
    (message "I am in list back at level-2 indentation")
    #+end_src
- List item 2
  #+begin_src emacs-lisp -n
  (message "I am in list back at level-1 indentation")
  #+end_src

#+begin_src emacs-lisp -n
(message "And now I am at level-0 indentation")
#+end_src
** Markdown source block with Hugo shortcodes                     :shortcode:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-md-with-hugo-shortcodes
:EXPORT_HUGO_CODE_FENCE: t
:END:
*** Shortcodes escaped
The =figure= shortcodes in the two Markdown source code blocks below
should *not* be expanded.. they should be visible verbatim.

- {&lbrace;< .. >}&rbrace; --- [[https://gohugo.io/content-management/shortcodes/#shortcodes-without-markdown][Shortcodes without Markdown]]
- {&lbrace;% .. %}&rbrace; --- [[https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown][Shortcodes with Markdown]]
**** Code block using code fences
#+begin_src md
{{< figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" >}}
{{% figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" %}}
#+end_src
**** Code block using =highlight= shortcode
Here, the =-n= switch is added to the Org source block to
auto-enable[fn:4] using the =highlight= shortcode.
#+begin_src md -n
{{< figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" >}}
{{% figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" %}}
#+end_src
*** Shortcodes *not* escaped
The =figure= shortcodes in the below example block *should* be
expanded.. you should be seeing little unicorns below.
#+begin_example
{{< figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" >}}
{{% figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" %}}
#+end_example
Above a =#+begin_example= .. =#+end_example= block is chosen
arbitrarily. The Hugo shortcodes will remain unescaped in *any*
source/example block except for _Markdown source blocks_ (annotated
with =md= language).
-----
*It is necessary to set the Hugo site config variable
=pygmentsCodeFences= to =true= for syntax highlighting to work for
fenced code blocks.*
** Source blocks with ATTR_HTML                      :attr___html:attr___css:
:PROPERTIES:
:EXPORT_FILE_NAME: source-blocks-with-attr-html
:END:
Some text.

#+attr_html: :class indent-block
#+attr_css: :padding-left 50px
#+begin_src emacs-lisp
(message (mapconcat #'identity
                    '("Hello," "how" "are" "you?")
                    " "))
#+end_src

Some more text.
** Org Source Block via Pygments                          :pygments:noexport:
:PROPERTIES:
:EXPORT_FILE_NAME: org-source-block-pygments
:END:
/This test case is not important after Hugo 0.28 as this was a
workaround for a limitation in the Pygments syntax highlighter. Hugo
0.28 onwards, the default syntax highlighter is Chroma, which does not
have that limitation, and thus no need for this workaround./
-----
Test case for the case where user has set
=org-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 [[https://discourse.gohugo.io/t/fenced-code-block-with-language-unsupported-by-pygments/7710][issue]] with Hugo will be seen if _all_ of the below are true:
- =pygmentsCodeFences = true= *and* =pygmentsUseClassic = true= (Hugo
  ≥ 0.28 -- default value is =false=) are set in the Hugo site
  =config.toml=.
- A source block's language is set to one that's not supported by
  Pygments (like [[https://bitbucket.org/birkenfeld/pygments-main/issues/719/wishlist-support-org][org]], and thus the below example with source code
  language set to =org=).
- =org-hugo-langs-no-descr-in-code-fences= is set to a value not
  containing that language descriptor (=org= in this case).
#+begin_src org
# Org comment
Export this post after setting
=org-hugo-langs-no-descr-in-code-fences= to =(org)= and temporarily
removing the =noexport= tag.
#+end_src
* Formatting                                                     :formatting:
** General
:PROPERTIES:
:EXPORT_DATE: 2017-07-31
:EXPORT_FILE_NAME: general-formatting
:END:
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~=    | =`key-binding`=                                                    | ~key-binding~         |
|                    | - if =org-hugo-use-code-for-kbd= is nil [default]                  |                       |
| =~key-binding~=    | =<kbd>key-binding</kbd>=                                           |                       |
|                    | - if =org-hugo-use-code-for-kbd= is non-nil                        |                       |
|                    | - Requires *CSS* to render the =<kbd>= tag as something special.   |                       |
| =+strike-through+= | =~~strike-through~~=                                               | +strike-through+      |
| =_underline_=      | =<span class = "underline">underline</span>=                       | _underline_           |
|                    | - Requires *CSS* to render this =underline= class as an underline. |                       |
|--------------------+--------------------------------------------------------------------+-----------------------|
** Keyboard tag
*** Use Org Code markup for =kbd= tag (default behavior)
:PROPERTIES:
:EXPORT_FILE_NAME: kbd-tag-default
:EXPORT_DATE: 2017-07-31
:END:
This is the default behavior. So =~C-h f~= will show up as =`C-h f`=
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~
*** Use Org Code markup for =kbd= tag
:PROPERTIES:
:EXPORT_HUGO_USE_CODE_FOR_KBD: t
:EXPORT_FILE_NAME: kbd-tag-yes
:EXPORT_DATE: 2017-07-31
:END:
Here the Org code markup is explicitly specified to be used for
=<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~
*** Don't Use Org Code markup for =kbd= tag
:PROPERTIES:
:EXPORT_HUGO_USE_CODE_FOR_KBD:
:EXPORT_FILE_NAME: kbd-tag-no
:EXPORT_DATE: 2017-07-31
:END:
Note that to disable the "use code for kbd" option, the value portion
of the property needs to be left *empty* instead of setting to =nil=!
#+begin_example
:PROPERTIES:
:EXPORT_HUGO_USE_CODE_FOR_KBD:
:END:
#+end_example

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~
*** COMMENT Using the new 'kbd' macro from Org =master=
:PROPERTIES:
:EXPORT_FILE_NAME: kbd-macro-org-9-2
:END:
- {{{kbd(C-h f)}}}
- {{{kbd(C-x SPC)}}}
- {{{kbd(M-RET)}}}
** Multi-line bold
:PROPERTIES:
:EXPORT_FILE_NAME: multi-line-bold
:END:
*This works fine as the bold sentence does not include a newline.*

*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:
#+begin_src emacs-lisp
(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))
#+end_src
* Example block                                                     :example:
** Simple
:PROPERTIES:
:EXPORT_DATE: 2017-07-19
:EXPORT_FILE_NAME: example-simple
:END:
#+begin_example
This is an example
#+end_example
** Example blocks with line number annotation
:PROPERTIES:
:EXPORT_FILE_NAME: example-block-with-line-numbers
:END:
- [[https://orgmode.org/manual/Literal-examples.html][Org reference]]
- [[https://gohugo.io/content-management/syntax-highlighting/][Hugo =highlight= shortcode with line numbers]]
*** Default new line number start
#+begin_example -n
line 1
 line 2
#+end_example
*** Specify new line number start
#+begin_example -n 20
line 20
line 21
#+end_example
*** Default continued line numbers
#+begin_example +n
 line 22
line 23
#+end_example
*** Specify continued line numbers jump
#+begin_example +n 10
line 33
line 34
#+end_example
** Example blocks with ATTR_HTML                     :attr___html:attr___css:
:PROPERTIES:
:EXPORT_FILE_NAME: example-blocks-with-attr-html
:END:
Some text.

#+attr_html: :class indent-block
#+attr_css: :padding-left 50px
#+begin_example
This is an example
Line 2
Line 3
#+end_example

Some more text.
* Menu in front matter                                                 :menu:
** Menu Meta Data in TOML Front Matter
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "something here" :weight 80 :parent posts :identifier foo1
:END:
*** Overriding few menu properties
:PROPERTIES:
:EXPORT_FILE_NAME: menu-alist-meta-data-toml-override-partial
:EXPORT_DATE: 2017-07-18
:EXPORT_HUGO_MENU_OVERRIDE: :weight 10 :identifier ov-partial
:END:
For 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:
#+begin_example
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.
#+end_example
*** Overriding menu properties completely
:PROPERTIES:
:EXPORT_FILE_NAME: menu-alist-meta-data-toml-override-full
:EXPORT_DATE: 2017-07-18
:EXPORT_HUGO_MENU: :menu test :weight 50
:END:
For this post, we see that no menu properties are inherited from the
parent; only the menu properties set in his subtree are effective.
*** Auto assign weights
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "auto weight"
:END:
**** Post with menu 1
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-menu-1
:EXPORT_DATE: 2017-07-20
:END:
**** Post with menu 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-menu-2
:EXPORT_DATE: 2017-07-20
:END:
**** Post with menu 3
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-menu-3
:EXPORT_DATE: 2017-07-20
:END:
**** Post with menu 4
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-menu-4
:EXPORT_DATE: 2017-07-20
:END:
**** Post with menu 5
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-menu-5
:EXPORT_DATE: 2017-07-20
:END:
*** Menu Title property                                               :title:
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu test :title "Page title for menu"
:EXPORT_FILE_NAME: menu-title-property
:END:
The =title= property for menu entries was introduced in Hugo v0.32 in
[[https://github.com/gohugoio/hugo/commit/9df3736fec164c51d819797416dc263f2869be77][this commit]].
** Menu Meta Data in YAML Front Matter                                 :yaml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
*** White space in menu entry
:PROPERTIES:
:EXPORT_FILE_NAME: menu-meta-data-yaml2
:EXPORT_DATE: 2017-07-19
:EXPORT_HUGO_MENU: :menu "something here" :weight 25
:END:
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.
*** White space in menu name
:PROPERTIES:
:EXPORT_FILE_NAME: menu-meta-data-yaml3
:EXPORT_DATE: 2017-07-19
:EXPORT_HUGO_MENU: :menu main :weight 25 :parent posts :name "Menu in YAML"
:END:
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 name property.
* Custom front matter                                             :custom_fm:
** Custom front matter in one line
:PROPERTIES:
:EXPORT_FILE_NAME: custom-front-matter-one-line
:EXPORT_DATE: 2017-07-24
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :foo bar :baz zoo :alpha 1 :beta "two words" :gamma 10 :version "6.17.00"
:END:
** Custom front matter in multiple lines
:PROPERTIES:
:EXPORT_FILE_NAME: custom-front-matter-multiple-lines
:EXPORT_DATE: 2017-07-24
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :foo bar
: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 10
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :empty_string ""
:END:
From [[https://orgmode.org/manual/Property-syntax.html][*(org) Property syntax*]]:
#+begin_quote
   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.
#+end_quote

#+begin_example
,* 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:
#+end_example
** Custom front matter with list values                         :list_values:
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :animals '(dog cat "penguin" "mountain gorilla")
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :strings-symbols '("abc" def "two words")
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :integers '(123 -5 17 1_234)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :floats '(12.3 -5.0 -17E-6)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :booleans '(true false)
:END:
*** Custom front matter with list values in TOML
:PROPERTIES:
:EXPORT_FILE_NAME: custom-front-matter-with-list-values-toml
:EXPORT_HUGO_FRONT_MATTER_FORMAT: toml
:END:
{{{oxhugoissue(99)}}}
*** Custom front matter with list values in YAML
:PROPERTIES:
:EXPORT_FILE_NAME: custom-front-matter-with-list-values-yaml
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
{{{oxhugoissue(99)}}}
** Custom front matter with table values or nested maps :TOML_table:nested_map:
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :dog '((legs . 4) ("eyes" . 2) (friends . (poo boo)))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header '((image . "projects/Readingabook.jpg") (caption . "stay hungry, stay foolish"))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :collection '((animals . (dog cat "penguin" "mountain gorilla")) (nothing) (nonnil . t) (strings-symbols . ("abc" def "two words")) (integers . (123 -5 17 1_234)) (floats . (12.3 -5.0 -17E-6)) (booleans . (true false)))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :random '((foo . bar))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :empty_string_value '((empty . ""))
:END:
*** Custom front matter with nested maps in TOML
:PROPERTIES:
:EXPORT_FILE_NAME: custom-front-matter-with-nested-maps-toml
:EXPORT_HUGO_FRONT_MATTER_FORMAT: toml
:END:
#+begin_description
Custom TOML front-matter with TOML tables.
#+end_description
{{{oxhugoissue(139)}}}
*** Custom front matter with nested maps in YAML
:PROPERTIES:
:EXPORT_FILE_NAME: custom-front-matter-with-nested-maps-yaml
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
#+begin_description
Custom YAML front-matter with nested maps.
#+end_description
{{{oxhugoissue(139)}}}
** Front-matter values with BigInts                             :bigint:toml:
:PROPERTIES:
:EXPORT_FILE_NAME: front-matter-bigint-value
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :small_int "234" :big_int "10040216507682529280"
:END:
#+begin_description
Test that front-matter values that are integers represented as
strings, but cannot be stored as 64-bit signed integers are
left as strings.
#+end_description

In this test, the small integer "234" (i.e. the one that can be
represented as a 64-bit signed integer) is saved as an integer in the
TOML front-matter.

But the big integer "10040216507682529280" which would need more than
64-bits to be stored as a signed integer is left as a string in the
TOML front-matter.
** Custom front matter value via Elisp                                :elisp:
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :attendees (xeijin/conv-chkbox-items-to-front-matter "Attendees")
:EXPORT_AUTHOR: xeijin
:END:
*** Meeting 1
:PROPERTIES:
:EXPORT_FILE_NAME: custom-fm-convert-chkbox-list-to-fm-1
:END:
{{{oxhugoissue(272)}}}
**** Attendees                                                     :noexport:
- [X] Attendee 1
- [-] Attendee 2
- [ ] Attendee 3
- Attendee 4
**** Notes
My notes
*** Meeting 2
:PROPERTIES:
:EXPORT_FILE_NAME: custom-fm-convert-chkbox-list-to-fm-2
:END:
{{{oxhugoissue(272)}}}
**** Attendees                                                     :noexport:
- [X] Attendee x
- [-] Attendee y
- [X] Attendee z
- Attendee w
**** Notes
My notes
* Resources                                                       :resources:
** TOML                                                                :toml:
*** Post with resources in front-matter (TOML)
:PROPERTIES:
:EXPORT_FILE_NAME: resources-in-front-matter-toml
:EXPORT_HUGO_RESOURCES: :src "image-4.png" :title "TOML: The Fourth Image"
:EXPORT_HUGO_RESOURCES+: :src "*.png" :name "my-cool-image-:counter" :title "TOML: The Image #:counter"
:EXPORT_HUGO_RESOURCES+: :src "*.png" :byline "bep"
:EXPORT_HUGO_RESOURCES+: :src "*.jpg" :title "JPEG Image #:counter"
:END:
*** Only custom resource params
:PROPERTIES:
:EXPORT_FILE_NAME: resources-only-custom-params
:EXPORT_HUGO_RESOURCES: :src "*.png" :foo "bar"
:END:
*** Custom resource params with list values
:PROPERTIES:
:EXPORT_FILE_NAME: resources-custom-params-list-values-toml
:EXPORT_HUGO_RESOURCES: :src "*.png" :animals '(dog cat "penguin" "mountain gorilla")
:EXPORT_HUGO_RESOURCES+: :strings-symbols '("abc" def "two words")
:EXPORT_HUGO_RESOURCES+: :integers '(123 -5 17 1_234)
:EXPORT_HUGO_RESOURCES+: :floats '(12.3 -5.0 -17E-6)
:EXPORT_HUGO_RESOURCES+: :booleans '(true false)
:EXPORT_HUGO_RESOURCES+: :foo bar
:END:
*** No "src" in resources front-matter         :dont_export_during_make_test:
:PROPERTIES:
:EXPORT_FILE_NAME: resources-no-src
:EXPORT_HUGO_RESOURCES: :foo "bar"
:END:
This is illegal --- You'll get a user-error.

The =src= field *must* be specified for the =resources= front-matter.
*** Header image using Resources                               :header:image:
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: header-image-using-resources
:EXPORT_FILE_NAME: index
:EXPORT_AUTHOR: Eastern Zhang
:EXPORT_DATE: 2018-03-01T00:10:00+08:00
:EXPORT_HUGO_RESOURCES: :src "stay_hungry*.jpg" :title "Stay Hungry Stay Foolish"
:EXPORT_HUGO_RESOURCES+: :caption "Stay Hungry Stay Foolish"
:EXPORT_HUGO_RESOURCES+: :credit "quotefancy.com"
:EXPORT_HUGO_RESOURCES+: :url "https://quotefancy.com/quote/13609/Steve-Jobs-Stay-hungry-Stay-foolish"
:END:
#+begin_description
Using the Hugo Resources feature for post header images.
#+end_description

This test suggests an alternative way to do what the OP wants in
{{{oxhugoissue(139)}}}.

Instead of having a TOML front-matter like:
#+begin_src conf-toml
+++
title = "fourth test"
author = ["Eason Zhang"]
date = 2018-03-01T00:10:00+08:00
lastmod = 2018-03-01T00:18:00+08:00
tags = ["project"]
draft = true
summary = "summary"
image_preview = "projects/bubbles.jpg"
[header]
  image = "projects/Readingabook.jpg"
  caption = "stay hungry, stay foolish"
+++
#+end_src

this post shows an example of doing something similar by exporting the
post as a *Page Bundle* and using the *Resources* feature. Here's how
the resource config and other front-matter is set in Org:
#+begin_src org
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: header-image-using-resources
:EXPORT_FILE_NAME: index
:EXPORT_AUTHOR: Eastern Zhang
:EXPORT_DATE: 2018-03-01T00:10:00+08:00
:EXPORT_HUGO_RESOURCES: :src "stay_hungry*.jpg" :title "Stay Hungry Stay Foolish"
:EXPORT_HUGO_RESOURCES+: :caption "Stay Hungry Stay Foolish"
:EXPORT_HUGO_RESOURCES+: :credit "quotefancy.com"
:EXPORT_HUGO_RESOURCES+: :url "https://quotefancy.com/quote/13609/Steve-Jobs-Stay-hungry-Stay-foolish"
:END:
#+end_src
** YAML                                                                :yaml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
*** Post with resources in front-matter (YAML)
:PROPERTIES:
:EXPORT_FILE_NAME: resources-in-front-matter-yaml
:EXPORT_HUGO_RESOURCES: :src "image-4.png" :title "The Fourth Image"
:EXPORT_HUGO_RESOURCES+: :src "*.png" :name "my-cool-image-:counter" :title "The Image #:counter"
:EXPORT_HUGO_RESOURCES+: :src "*.png" :byline "bep"
:EXPORT_HUGO_RESOURCES+: :src "*.jpg" :title "JPEG Image #:counter"
:END:
*** Custom resource params with list values
:PROPERTIES:
:EXPORT_FILE_NAME: resources-custom-params-list-values-yaml
:EXPORT_HUGO_RESOURCES: :src "*.png" :animals '(dog cat "penguin" "mountain gorilla")
:EXPORT_HUGO_RESOURCES+: :strings-symbols '("abc" def "two words")
:EXPORT_HUGO_RESOURCES+: :integers '(123 -5 17 1_234)
:EXPORT_HUGO_RESOURCES+: :floats '(12.3 -5.0 -17E-6)
:EXPORT_HUGO_RESOURCES+: :booleans '(true false)
:EXPORT_HUGO_RESOURCES+: :foo bar
:END:
* Outputs                                                           :outputs:
** Output HTML and JSON                                                :json:
:PROPERTIES:
:EXPORT_FILE_NAME: output-html-and-json
:EXPORT_HUGO_OUTPUTS: html json
:END:
*Note*: A =single.json= is required to be at a valid location in the
template lookup hierarchy for the JSON outputs to be created.

[[./index.json][Here's the JSON output version of this page]].
** Setting empty outputs is fine                                      :empty:
:PROPERTIES:
:EXPORT_FILE_NAME: output-empty
:EXPORT_HUGO_OUTPUTS:
:END:
If the =EXPORT_HUGO_OUTPUTS= property is left empty/unset, =ox-hugo=
will not set the =outputs= variable in the front-matter at all. So
only the HTML output will be created (default).
* Post body                                                            :body:
** Summary Splitter                                   :summary_splitter:more:
*** Summary Splitter
:PROPERTIES:
:EXPORT_FILE_NAME: summary-splitter
:EXPORT_DATE: 2017-07-21
:END:
Here is the summary.
#+hugo: more
Here is text after the [[https://gohugo.io/content-management/summaries#user-defined-manual-summary-splitting][summary splitter]].
*** COMMENT Summary Splitter at EOF                                     :eof:
:PROPERTIES:
:EXPORT_FILE_NAME: summary-splitter-at-eof
:END:
#+begin_description
Summary splitter at the end of post
#+end_description
{{{oxhugoissue(152)}}}

/Uncomment this test after the upstream bug reported in
=markdown-mode= # [[https://github.com/jrblevin/markdown-mode/issues/327][327]] gets resolved./

Here more summary.
#+hugo: more
** Dealing with underscores
:PROPERTIES:
:EXPORT_FILE_NAME: dealing-with-underscores
:EXPORT_DATE: 2017-07-21
:END:
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: :raised_hands:

And these ones should be eventually removed and _underline_ the text
(/Requires CSS to do so./) -- *Org syntax*.
** Nested bold and italics
:PROPERTIES:
:EXPORT_DATE: 2017-07-22
:EXPORT_FILE_NAME: nested-bold-italics
:END:
- /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.*
** Italicize links with underscores                 :italic:links:underscore:
:PROPERTIES:
:EXPORT_FILE_NAME: italicize-links-with-underscores
:END:
#+begin_description
Test that links with underscores can be italicized/emboldened/both.
#+end_description
{{{oxhugoissue(170)}}}
*** External links
- Italic :: /What is a [[https://en.wikipedia.org/wiki/Two%27s_complement][two's complement]]?/
- Bold :: *What is a [[https://en.wikipedia.org/wiki/Two%27s_complement][two's complement]]?*
- Bold + Italic :: /*What is a [[https://en.wikipedia.org/wiki/Two%27s_complement][two's complement]]?*/
*** Internal links
- Italic :: /Link to [[file:single-posts/post_with_underscore_in_name.org][another post on this site]]?/
- Bold :: *Link to [[file:single-posts/post_with_underscore_in_name.org][another post on this site]]?*
- Bold + Italic :: /*Link to [[file:single-posts/post_with_underscore_in_name.org][another post on this site]]?*/
** Single and Double quotes
:PROPERTIES:
:EXPORT_FILE_NAME: single-double-quotes
:EXPORT_DATE: 2017-07-22
:END:
The strings in these two columns should look the exact same.
|   | 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/>”. |
#+tblfm: $1=@#-1

*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./
** /ndash/ `and` *mdash*
:PROPERTIES:
:EXPORT_FILE_NAME: ndash-and-mdash
:EXPORT_DATE: 2017-07-22
:END:
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              |
#+tblfm: $1=@#-1
*** Title sanitization
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".
** Escaping hashes and exclamations correctly in body
:PROPERTIES:
:EXPORT_FILE_NAME: escaping-hashes-and-exclamations-in-body
:END:
I intend to show these # characters verbatim; they should not render
as Markdown headings. They also shouldn't show up with a leading =\=
in the final rendered output.

# This is an Org comment

#This is not an Org comment. It has a hash char at beginning of a
paragraph which must be escaped just once i.e. show up as =\#= in
Markdown.

blah # This isn't an Org comment either

This * will be escaped just once i.e. show up as =\*= in Markdown.

This _ will be escaped just once i.e. show up as =\_= in Markdown.

This \ will be escaped just once i.e. show up as =\\= in Markdown.

Hash char at beginning of a continued line
#like this must be escaped just once i.e. show up as =\#= in Markdown.

![this exclamation must be escaped just once i.e. show up as =\!= in
Markdown]

This ! does not need to be escaped as there is no ambiguity.
** Force line break / Center align                         :force:line_break:
*** Force line break
:PROPERTIES:
:EXPORT_FILE_NAME: force-line-break
:END:
From [[https://orgmode.org/manual/Paragraphs.html][=C-h i g (org) Paragraphs=]]:

#+begin_quote
Paragraphs are separated by at least one empty line.  If you need to
enforce a line break within a paragraph, use ‘\\’ at the end of a line.
#+end_quote

Line 1 \\
Line 2
*** Center align                                               :center_align:
:PROPERTIES:
:EXPORT_FILE_NAME: center-align
:END:
From [[https://orgmode.org/manual/Paragraphs.html][=C-h i g (org) Paragraphs=]]:

#+begin_quote
If you would like to center some text, do it like this:

#+begin_src org
,#+begin_center
Everything should be made as simple as possible, \\
but not any simpler
,#+end_center
#+end_src
#+end_quote

#+begin_center
Everything should be made as simple as possible, \\
but not any simpler
#+end_center
**** Testing emphasis in Org center block
#+begin_center
*bold* \\
/italics/ \\
+strikethrough+
#+end_center
** Wrapping Org headings in HTML tags   :wrapping:headings:section:tags:HTML:
:PROPERTIES:
:EXPORT_FILE_NAME: wrapping-org-headings-in-html-tags
:END:
#+begin_description
Test the workaround for wrapping Org headings in HTML tags like
~section~ and ~div~.
#+end_description
{{{oxhugoissue(160)}}}
*** Org Source
#+begin_src org
,#+html: <style>.left { float: left; width: 45%;} .right { float: right; width: 45%;}</style>

,#+html: <section class="left">
# Hack to get around Blackfriday limitation: https://github.com/kaushalmodi/ox-hugo/issues/93
,#+html: <section></section>
,**** This section will show up on the left side
Content in the left side section
,#+html: </section>

,#+html: <section class="right">
,#+html: <section></section>
,**** This section will show up on the right side
Content in the right side section
,#+html: </section>

# Clear the floats
,#+html: <div style="clear: both;"></div>
#+end_src
*** Output
#+html: <style>.left { float: left; width: 45%;} .right { float: right; width: 45%;}</style>

#+html: <section class="left">
# Hack to get around Blackfriday limitation: https://github.com/kaushalmodi/ox-hugo/issues/93
#+html: <section></section>
**** This section will show up on the left side
Content in the left side section
#+html: </section>

#+html: <section class="right">
#+html: <section></section>
**** This section will show up on the right side
Content in the right side section
#+html: </section>

# Clear the floats
#+html: <div style="clear: both;"></div>
* Page Bundles                                                 :page_bundles:
:PROPERTIES:
:EXPORT_HUGO_SECTION: bundles
:END:
** Bundles Section
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:END:
This is the content for the "bundles" section landing page.
** Page Bundle A
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: page-bundle-a
:END:
*** Page Bundle A
:PROPERTIES:
:EXPORT_FILE_NAME: index
:EXPORT_HUGO_RESOURCES: :src "images/copy-of-*.png" :title "First copy of Org mode logo"
:EXPORT_HUGO_RESOURCES+: :src "copy-2-*.png" :title "Second copy of Org mode logo"
:END:
Index page of /Page Bundle A/.
**** Link to images not in the current directory
***** Source path contains =/static/=
When path contains =/static/=, the path translations are the exact
same as those for non-bundle cases.

[[/posts/image-links/#path-containing-static][More details]]

[[../files-to-be-copied-to-static/static/images/copy-of-unicorn-logo-page-bundle.png]]
***** Source path contains the *bundle name*
See [[/images-in-content/page-bundle-images-in-same-dir/][this other test]] for examples.
|-------------------------------------------+----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------|
| Inside =<ORG_FILE_DIR>=                   | Copied-to location inside BUNDLE                         | Explanation                                                                                                             |
|-------------------------------------------+----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------|
| =<ORG_FILE_DIR>/bar/<BUNDLE>/baz/foo.png= | =<HUGO_BASE_DIR>/content/<SECTION>/<BUNDLE>/baz/foo.png= | If the file directory path contains ="/<BUNDLE>/"=, the directory structure following that ="/<BUNDLE>/"= is preserved. |
|-------------------------------------------+----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------|
****** Special case: Home page branch bundle
In this case, both =HUGO_SECTION= and =HUGO_BUNDLE= values will be
=/=.

So the images to be copied to the *home page branch bundle* i.e. the
=content/= dir must be placed in a special =_home/= directory. Here
are some examples:
|----------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Inside =<ORG_FILE_DIR>=                | Copied-to location inside BUNDLE      | Explanation                                                                                                                                                    |
|----------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| =<ORG_FILE_DIR>/bar/_home/baz/foo.png= | =<HUGO_BASE_DIR>/content/baz/foo.png= | If the page is the home page branch bundle, and the file directory path contains ~"/_home/"~, the directory structure following that ~"/_home/"~ is preserved. |
| =<ORG_FILE_DIR>/bar/_home/foo.png=     | =<HUGO_BASE_DIR>/content/foo.png=     |                                                                                                                                                                |
|----------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------|
***** Source path contains neither =/static/= nor the *bundle name*
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]]
|----------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------|
| Outside =static=                 | Copied-to location inside BUNDLE                             | Explanation                                                                                                                                       |
|----------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------|
| =~/temp/bar/baz/foo.png=         | =<HUGO_BASE_DIR>/content/<SECTION>/<BUNDLE>/foo.png=         | Here, as the *outside* path does not have =/static/=, the file is copied directly to the BUNDLE dir.                                              |
|----------------------------------+--------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------|
****** Same image, but hyperlinked
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png][file:../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]]
***** Page Bundles with images in the same dir as content Org file
|-------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------|
| Inside =<ORG_FILE_DIR>=                   | Copied-to location inside BUNDLE                             | Explanation                                                                                                                                    |
|-------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------|
| =<ORG_FILE_DIR>/bar/baz/foo.png=          | =<HUGO_BASE_DIR>/content/<SECTION>/<BUNDLE>/bar/baz/foo.png= | Even if the *outside* path does not have =/static/=, it is still inside the same dir as the Org file, so the directory structure is preserved. |
|-------------------------------------------+--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------|
See [[/images-in-content/page-bundle-images-in-same-dir/][this other test]] for an example.
*** Bundled page foo
:PROPERTIES:
:EXPORT_FILE_NAME: foo
:END:
"Foo" page in /Page Bundle A/.
*** Bundled page bar
:PROPERTIES:
:EXPORT_FILE_NAME: bar
:END:
"Bar" page in /Page Bundle A/.
** Page Bundle B
:PROPERTIES:
:EXPORT_FILE_NAME: index
:EXPORT_HUGO_BUNDLE: page-bundle-b
:END:
Index page of /Page Bundle B/.

[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]]
** Headless Page Bundle                                            :headless:
*** Headless Page Bundle X
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: headless-page-bundle-x
:END:
**** Headless Page Bundle Index Page
:PROPERTIES:
:EXPORT_FILE_NAME: index
:EXPORT_HUGO_HEADLESS: t
:END:
This is a *headless* page bundle. This feature was introduced in [[https://github.com/gohugoio/hugo/commit/0432c64dd22e4610302162678bb93661ba68d758][this
commit]], and available in Hugo v0.35+.

As this bundle is headless, the *index* page of this bundle (this
page!) will not be published anywhere:
- It will have no =Permalink= and no rendered HTML in =public/=.
- It will not be part of =.Site.RegularPages=, etc.

But you can get it by =.Site.GetPage ...=. Here is an example ([[https://github.com/gohugoio/hugo/issues/4311#issuecomment-359461045][ref]]):
#+begin_example
{{ $headless := .Site.GetPage "page" "some-headless-page" }}
{{ $reusablePages := $headless.Resources.Match "sidebar-content*" }}
{{ range $reusablePages }}
    {{ .Title }}
{{ end }}
#+end_example

There are many use cases of such headless page bundles:
- Shared media galleries
- Reusable page content "snippets"
**** Bundled page foo in the headless bundle
:PROPERTIES:
:EXPORT_FILE_NAME: foo
:END:
"Foo" page in /Headless Page Bundle/.
**** Bundled page bar in the headless bundle
:PROPERTIES:
:EXPORT_FILE_NAME: bar
:END:
"Bar" page in /Headless Page Bundle/.
**** Bundled page zoo in the headless bundle
:PROPERTIES:
:EXPORT_FILE_NAME: zoo
:END:
"Zoo" page in /Headless Page Bundle/.
*** Page using the Headless Page Bundle X                            :layout:
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:EXPORT_FILE_NAME: page-using-headless-page-bundle
:EXPORT_HUGO_LAYOUT: headless-bundle-single
:END:
This is a regular page. Below content is fetched from the *headless
page bundle* =headless-page-bundle-x=.
 - [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/bundles/headless-page-bundle-x/index.md][Source (~index.md~)]] of the referenced headless bundle.
* Footnotes Test                                                   :footnote:
** Footnotes 1
:PROPERTIES:
:EXPORT_DATE: 2017-07-21
:EXPORT_FILE_NAME: footnotes-1
:END:
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./
** Footnotes 2
:PROPERTIES:
:EXPORT_DATE: 2017-07-21
:EXPORT_FILE_NAME: footnotes-2
:END:
This is some text[fn:2].
** Footnotes in a row
:PROPERTIES:
:EXPORT_FILE_NAME: footnotes-in-a-row
:EXPORT_DATE: 2017-07-21
:END:
This is some text[fn:1][fn:2].
** Multiple references of same footnote
:PROPERTIES:
:EXPORT_FILE_NAME: multi-ref-same-footnote
:EXPORT_DATE: 2017-07-21
:END:
This is some text[fn:1].
This is some text[fn:1].
This is some text[fn:1].
** Multi-line footnote
:PROPERTIES:
:EXPORT_FILE_NAME: multi-line-footnote
:END:
This is some text[fn:3].
** Multi-line footnote Japanese
:PROPERTIES:
:EXPORT_FILE_NAME: multi-line-footnote-japanese
:EXPORT_HUGO_LOCALE: ja
:END:
Here is a footnote where it originally had Japanese text on both
lines[fn:6].

Here is a footnote where originally the first line ended in English
but next line started with Japanese[fn:7].

Here is a footnote entirely in English[fn:3].
** Bind footnotes to the preceding word
:PROPERTIES:
:EXPORT_FILE_NAME: footnotes-bind-to-preceding-word
:EXPORT_HUGO_ALIASES: footnotes-at-eol
:END:
{{{oxhugoissue(96)}}}

To test the fix for this, increase/decrease the width of the browser
window showing this page so that the test lines below start wrapping
around, and you will see that the footnote references will *never* be
on their own on a new line.
*** Footnote ref at EOL
**** Last word, followed by FOOTNOTE PERIOD --- /Good Case A/
- As there is no space in-between "word FOOTNOTE PERIOD", this text
  will stay unmodified.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1].

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1].

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1].

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1].
**** Last word, followed by FOOTNOTE *space* PERIOD --- /Bad Case A1/
- In this case, the *space* before the PERIOD at EOL is removed.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1] .

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1] .

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1] .

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1] .
**** Last word, followed by PERIOD *space* FOOTNOTE --- /Bad Case A2/
- In this case, the *space* before FOOTNOTE is replaced with =&nbsp;=.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a. [fn:1]

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a. [fn:1]

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a. [fn:1]

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a. [fn:1]
**** Last word, followed by *space* FOOTNOTE *space* PERIOD --- /Bad Case A3/
- This is a blend of /Bad Case A1/ and /Bad Case A2/ above.
- In this case, the *space* before FOOTNOTE is replaced with =&nbsp;=,
  *AND* the *space* before the PERIOD at EOL is removed.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a [fn:1] .

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a [fn:1] .

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a [fn:1] .

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a [fn:1] .

abcde a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a [fn:1] .
*** Footnote NOT at EOL
**** Word, followed by FOOTNOTE PERIOD --- /Good Case B/
- As there is no space in-between "word FOOTNOTE PERIOD", this text
  will stay unmodified.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1]. B b b.

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1]. B b b.

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1]. B b b.

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1].
**** Word, followed by FOOTNOTE *space* PERIOD --- /Bad Case B1/
- In this case, the *space* before the PERIOD at EOL is removed.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1] . B b b.

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a[fn:1] . B b b.

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1] . B b b.

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a[fn:1] . B b b.
**** Word, followed by PERIOD *space* FOOTNOTE --- /Bad Case B2/
- In this case, the *space* before FOOTNOTE is replaced with =&nbsp;=.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a. [fn:1] B b b.

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a. [fn:1] B b b.

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a. [fn:1] B b b.

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a. [fn:1] B b b.
**** Word, followed by *space* FOOTNOTE *space* PERIOD --- /Bad Case B3/
- This is a blend of /Bad Case B1/ and /Bad Case B2/ above.
- In this case, the *space* before FOOTNOTE is replaced with =&nbsp;=,
  *AND* the *space* before the PERIOD at EOL is removed.

a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a [fn:1] . B b b.

ab a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a [fn:1] . B b b.

abc a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a [fn:1] . B b b.

abcd a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a [fn:1] . B b b.

abcde a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a a
a a a [fn:1] . B b b.
* Tags
** Basic tags                                                       :abc:def:
:PROPERTIES:
:EXPORT_FILE_NAME: test-tags
:EXPORT_DATE: 2017-07-12T13:48:01-04:00
:END:
Testing tags set using Org tags in headings.
** Prefer hyphens and allow spaces
:PROPERTIES:
:EXPORT_HUGO_PREFER_HYPHEN_IN_TAGS: t
:EXPORT_HUGO_ALLOW_SPACES_IN_TAGS: t
:END:
*** Hyphens and spaces in tags      :an_apple__a___pear:good__bad__and__ugly:
:PROPERTIES:
:EXPORT_FILE_NAME: hyphens-and-spaces-in-tags
:END:
*** Hyphens and spaces in categories :@an_apple__a___pear:@good__bad__and__ugly:
:PROPERTIES:
:EXPORT_FILE_NAME: hyphens-and-spaces-in-categories
:END:
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=.
** Hyphens in Org tags
*** Prefer
:PROPERTIES:
:EXPORT_HUGO_PREFER_HYPHEN_IN_TAGS: t
:END:
**** Prefer Hyphen in Tags    :_a:___a:b_:b___:a_b:a___b:a_b___c:_a_b___c___:
:PROPERTIES:
:EXPORT_FILE_NAME: hyphen-tags-prefer
:END:
**** Prefer Hyphen Categories :@_a:@___a:@b_:@b___:@a_b:@a___b:@a_b___c:@_a_b___c___:
:PROPERTIES:
:EXPORT_FILE_NAME: hyphen-categories-prefer
:END:
*** Don't Prefer
:PROPERTIES:
:EXPORT_HUGO_PREFER_HYPHEN_IN_TAGS:
:END:
**** Don't Prefer Hyphen in Tags          :_a:_a:b_:b_:a_b:a_b:a_b_c:_a_b_c_:
:PROPERTIES:
:EXPORT_FILE_NAME: hyphen-tags-dont-prefer
:END:
**** Don't Prefer Hyphen Categories :@_a:@_a:@b_:@b_:@a_b:@a_b:@a_b_c:@_a_b_c_:
:PROPERTIES:
:EXPORT_FILE_NAME: hyphen-categories-dont-prefer
:END:
** Spaces in Org Tags
*** Want Spaces
:PROPERTIES:
:EXPORT_HUGO_ALLOW_SPACES_IN_TAGS: t
:END:
**** Spaces in tags               :abc__def:abc__def__ghi:abc__def__ghi__jkl:
:PROPERTIES:
:EXPORT_FILE_NAME: spaces-in-tags
:END:
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 tag =abc def=.
**** Spaces in categories      :@abc__def:@abc__def__ghi:@abc__def__ghi__jkl:
:PROPERTIES:
:EXPORT_FILE_NAME: spaces-in-categories
:END:
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=.
*** Don't Want Spaces
:PROPERTIES:
:EXPORT_HUGO_ALLOW_SPACES_IN_TAGS:
:END:
**** No Spaces in tags            :abc__def:abc__def__ghi:abc__def__ghi__jkl:
:PROPERTIES:
:EXPORT_FILE_NAME: no-spaces-in-tags
:END:
**** No Spaces in categories   :@abc__def:@abc__def__ghi:@abc__def__ghi__jkl:
:PROPERTIES:
:EXPORT_FILE_NAME: no-spaces-in-categories
:END:
** Tags as Categories
*** Category A                                                        :@catA:
**** Cat A post 1                                                      :meow:
:PROPERTIES:
:EXPORT_DATE: 2017-07-24
:EXPORT_FILE_NAME: cat-a-post-1
:END:
This post is in category =catA= and tagged =meow=.
**** Cat A and cat B                                                  :@catB:
:PROPERTIES:
:EXPORT_FILE_NAME: cat-a-and-cat-b
:EXPORT_DATE: 2017-07-24
:END:
This gets both categories =catA= and =catB=.
** Do not leak post's immediate sub-heading tag into the front-matter :expected_tag:post_heading_followed_soon_with_subheading:
:PROPERTIES:
:EXPORT_FILE_NAME: dont-leak-subheading-tags
:END:
*** Sub-heading 1                                            :unexpected_tag:
This is a *special* case where:
- A post has a sub-heading as the first line in its body, and
- That sub-heading has a tag too!

The passing case for this test would be that the =unexpected_tag= does
not leak into the post's front-matter.
* Links                                                               :links:
** Links with target attribute
:PROPERTIES:
:EXPORT_FILE_NAME: links-with-target-attribute
:EXPORT_HUGO_BLACKFRIDAY: :hrefTargetBlank nil
:END:
#+attr_html: :target _blank :rel noopener
[[https://orgmode.org/manual/Hyperlinks.html][This link (to Hyperlinks chapter in Org manual)]] will open in a new tab
as it is annotated with ~target="_blank"~.

#+attr_html: :target _self
[[https://orgmode.org/manual/Hyperlinks.html][Here's the same link]] but with ~target="_self"~ annotation. So
clicking it will open that link in this same tab!

[[https://orgmode.org/manual/Hyperlinks.html][Here's the same link again]], but this time there is no =#+attr_html=
annotation. So the behavior of clicking this link will depend on the
browser (typically an external link will open in a new tab
automatically).
*** Image linked to image with =target= attribute

{{{oxhugoissue(133)}}}

#+attr_html: :width 10% :target _self
[[https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png][https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png]]

Above is an hyperlinked image with the HTML attributes set as
=#+attr_html: :width 10% :target _self= in Org.

- The =width= attribute of /10%/ must apply *only* to the image, and
  not to the link.
- And the ~target="_self"~ attribute must apply *only* to the link,
  and not the image. So, clicking that image will open the linked
  image in the same browser tab because the =target= is set to
  ="_self"= (*Hugo v0.37+* --- fixed in {{{hugopr(4382)}}}).

-----

#+attr_html: :width 10% :target _self
Here's an inline hyperlinked image with the exact same HTML
attributes: [[https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png][https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png]]. So,
clicking this image too should open the linked image in the same
brower tab.
** External Links                                            :external_links:
:PROPERTIES:
:EXPORT_FILE_NAME: external-links
:EXPORT_OPTIONS: broken-links:t
:END:
- [[ftp://ftp.gnu.org/gnu/emacs/][Emacs download (FTP)]]
- [[https://orgmode.org][Org mode (HTTPS)]]
- [[http://some.insecure.site][Dummy http link]]
*** Gopher link support
{{{oxhugoissue(132)}}}
# - [[gopher://some.gopher.site][Dummy gopher link]]

The /gopher/ link support requires user to add something like this to
their user config:
#+begin_src emacs-lisp
(with-eval-after-load 'org
  (defun org-link-gopher-export-link (link desc format)
    "Create export version of LINK and DESC to FORMAT."
    (let ((link (concat "gopher:" link)))
      (cond
       ((eq format 'html)
        (format "<a href=\"%s\">%s</a>" link desc))
       ((eq format 'latex)
        (format "\\href{%s}{%s}" link desc))
       (t                               ;`ascii', `md', `hugo', etc.
        (format "[%s](%s)" desc link)))))
  (org-link-set-parameters "gopher" :export #'org-link-gopher-export-link))
#+end_src

Once that is evaluated, links like these will export fine i.e. no
"Unable to resolve link" errors:
#+begin_src org
[[gopher://some.gopher.site][Dummy gopher link]]
#+end_src
*** Mailto link support
{{{oxhugoissue(149)}}}

[[mailto:abc@xyz.com][My email]]
** Within the same post (Internal links)                     :internal_links:
*** Link to headings by name                     :toc:headings:export_option:
:PROPERTIES:
:EXPORT_FILE_NAME: link-to-headings-by-name
:EXPORT_OPTIONS: num:t toc:t
:END:
**** Alpha 101
:PROPERTIES:
:UNNUMBERED: t
:END:
- Link (with description) to a heading with section number: [[* Beta 102][Link to
  /Beta 102/ heading]]
- Link (no description) to a heading without section number: [[* Zeta 103
  which has *some* /markup/]].

  The space after that =*= in the link is optional.. so this also
  works: [[*Zeta 103 which has *some* /markup/]].
**** Beta 102
- Link (with description) to a heading without section number: [[* Alpha 101][Link to
  /Alpha 101/ heading]]
***** Gamma 102.1
****** Delta 102.1.1
****** Epsilon 102.1.2
**** Zeta 103 which has *some* /markup/
:PROPERTIES:
:UNNUMBERED: t
:END:
***** Links (no descriptions) to headings with section numbers
- Section [[* Gamma 102.1]]
- Section [[* Delta 102.1.1]]
- Section [[* Epsilon 102.1.2]]
*** Link to a heading CUSTOM_ID
:PROPERTIES:
:EXPORT_FILE_NAME: link-heading-custom-id
:EXPORT_DATE: 2017-07-28
:END:
*Obviously, all the =CUSTOM_ID='s set by the user in this file have to
 be unique.*
**** Heading 1
:PROPERTIES:
:CUSTOM_ID: link-heading-1
:END:
- Link to [[#link-heading-2][Heading 2]]
#+include: "./misc/common.org::#lorem-ipsum" :only-contents t
#+include: "./misc/common.org::#lorem-ipsum" :only-contents t
#+include: "./misc/common.org::#lorem-ipsum" :only-contents t
#+include: "./misc/common.org::#lorem-ipsum" :only-contents t
**** Heading 2
:PROPERTIES:
:CUSTOM_ID: link-heading-2
:END:
- Link to [[#link-heading-1][Heading 1]]
*** Links to Org targets
:PROPERTIES:
:EXPORT_FILE_NAME: links-to-org-targets
:END:
From [[https://orgmode.org/manual/Internal-links.html][(org) Internal links]],

#+begin_src org
- one item
- <<target>>another item
Here we refer to item [[target]].
#+end_src

will output below (/lorem-ipsum/ added to increase page content so
that the link jump is evident):

- one item
- <<target>>another item

/Scroll to the end of the below 'lorem-ipsum' block to find the test
link./

#+include: "./misc/common.org::#lorem-ipsum" :only-contents t

*Here we refer to item [[target]].*
*** Links to source blocks                                        :src_block:
:PROPERTIES:
:EXPORT_FILE_NAME: links-to-source-blocks
:END:
#+begin_description
Test for internal links to source block references.
#+end_description
#+include: "./single-posts/links-to-org-elements.org::#links-to-source-blocks" :only-contents t
*** Links to tables                                           :table:caption:
:PROPERTIES:
:EXPORT_FILE_NAME: links-to-tables
:END:
#+begin_description
Test for internal links to table references.
#+end_description
#+include: "./single-posts/links-to-org-elements.org::#links-to-tables" :only-contents t
*** Links to images                                            :image:figure:
:PROPERTIES:
:EXPORT_FILE_NAME: links-to-images
:END:
#+begin_description
Test for internal links to image references.
#+end_description
#+include: "./single-posts/links-to-org-elements.org::#links-to-images" :only-contents t
*** Links to equations                                            :equations:
:PROPERTIES:
:EXPORT_FILE_NAME: links-to-equations
:END:
{{{oxhugoissue(130)}}}

\begin{equation}
\label{eq:1}
C = W\log_{2} (1+\mathrm{SNR})
\end{equation}

*Here we refer to equation \ref{eq:2}.*

Below, /lorem-ipsum/ is added to increase page content so that the
link jump is evident:

#+include: "./misc/common.org::#lorem-ipsum" :only-contents t

Here's the same equation again, but with a different label:

\begin{equation}
\label{eq:2}
C = W\log_{2} (1+\mathrm{SNR})
\end{equation}

*Here we refer to equation \ref{eq:1}.*
*** Radio targets                                             :radio_targets:
:PROPERTIES:
:EXPORT_FILE_NAME: radio-targets
:END:
#+begin_description
Testing [[https://orgmode.org/manual/Radio-targets.html][Radio targets]]
#+end_description
Here I am referencing to asdf123 that I talk about later.

#+include: "./misc/common.org::#lorem-ipsum" :only-contents t
#+include: "./misc/common.org::#lorem-ipsum" :only-contents t

Here I talk about the asdf123 topic again.

#+include: "./misc/common.org::#lorem-ipsum" :only-contents t
#+include: "./misc/common.org::#lorem-ipsum" :only-contents t

Here I talk about <<<asdf123>>>.
** Links outside the same post
:PROPERTIES:
:EXPORT_FILE_NAME: links-outside-the-same-post
:END:
{{{oxhugoissue(30)}}}
*** External links with search options                       :external_links:
Links between documents can contain some search options. Only links
to a heading with a *:CUSTOM_ID* property will be resolved to the
appropriate location in the linked file. Links to headlines and
links to targets will be resolved to the containing file.

- [[file:link-destination.org::#external-target][Link to CUSTOM_ID]]
- [[file:link-destination.org::*external-target][Link to a headline]]
- [[file:link-destination.org::external-target][Link to a target]]
*** Internal links                                           :internal_links:
Internal links point to targets in the current subtree that will be
exported to the same Hugo post as the link source. To handle links to
an *:ID* property, the =org-id= feature must first be loaded, either
through =org-customize= or by adding =(require 'org-id)= in your Emacs
init file.

- [[#internal-target][Link to CUSTOM_ID within the same post]]
- [[id:8e65ff86-3f9a-48ef-9b43-751a2e8a9372][Link to ID within the same post]]
- [[*Internal target][Link to headline within the same post]]
- [[internal-target][Link to target within the same post]]
*** Cross-post links                                        :crosspost_links:
Cross-post links are internal links pointing to targets in a different
subtree that will be exported to another Hugo post than the link
source in subtree-based exports. The Hugo's ~ref~ and ~relref~
shortcodes only supports anchors to headlines, so links to a heading,
a *:CUSTOM_ID* property, or an *:ID* property will be resolved to the
appropriate location in the linked file, but links to targets will be
resolved to the containing post.
**** Links without descriptions
- Link to CUSTOM_ID outside the same post: [[#external-target]]
- Link to ID outside the same post: [[id:de0df718-f9b4-4449-bb0a-eb4402fa5fcb]]
- Link to target outside the same post: [[*External target]]
- Another link to target outside the same post: [[* External target with *bold* and /italic/]]
- Link to subtree by CUSTOM_ID: [[#link-destination]]
- Link to subtree by ID: [[id:1e5e0bcd-caea-40ad-a75b-e488634c2678]]
- Link to subtree by headline: [[*Link destination]]
**** Links with descriptions
- [[#external-target][Link to CUSTOM_ID outside the same post]]
- [[id:de0df718-f9b4-4449-bb0a-eb4402fa5fcb][Link to ID outside the same post]]
- [[*External target][Link to target outside the same post]]
- [[* External target with *bold* and /italic/][Another link to target outside the same post]]
- [[#link-destination][Link to subtree by CUSTOM_ID]]
- [[id:1e5e0bcd-caea-40ad-a75b-e488634c2678][Link to subtree by ID]]
- [[*Link destination][Link to subtree by headline]]
*** Internal target
:PROPERTIES:
:CUSTOM_ID: internal-target
:ID:       8e65ff86-3f9a-48ef-9b43-751a2e8a9372
:END:
<<internal-target>>
*** Link destination
:PROPERTIES:
:CUSTOM_ID: link-destination
:EXPORT_FILE_NAME: link-destination
:ID:       1e5e0bcd-caea-40ad-a75b-e488634c2678
:END:
**** External target
:PROPERTIES:
:CUSTOM_ID: external-target
:ID:       de0df718-f9b4-4449-bb0a-eb4402fa5fcb
:END:
<<external-target>>
**** External target with *bold* and /italic/
** Url encoding in links                              :escaping:url:encoding:
:PROPERTIES:
:EXPORT_FILE_NAME: url-encoding-in-links
:END:
#+begin_description
Encoding of non-URL characters in links
#+end_description
Below links are invalid, they are there just for test purpose.

- [[https://jira.example.com/issues/?jql=(project=MYPRJ)AND(assignee=currentUser())][A dummy Jira JQL link]]
- [[https://jira.example.com/issues/?jql=(project=MYPRJ)AND(assignee=currentUser())AND(labels in (foo))][A dummy Jira JQL link with spaces]]
* Equations                                               :equations:mathjax:
** Inline equations
:PROPERTIES:
:EXPORT_FILE_NAME: equation-latex-frag
:EXPORT_DATE: 2017-07-31
:END:
#+begin_description
Inline and /one-per-line/ equations
#+end_description
- 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:
#+begin_src text
LaTeX formatted equation: \( E = -J \sum_{i=1}^N s_i s_{i+1} \)
#+end_src

will look like this in Hugo rendered HTML:

LaTeX formatted equation: \( E = -J \sum_{i=1}^N s_i s_{i+1 }\)

(Don't see this in Markdown, see what it looks after Hugo has
processed it.)

Here's another example, taken from [[https://orgmode.org/manual/LaTeX-fragments.html][(org) LaTeX fragments]].

Below in Org:
#+begin_example
If $a^2=b$ and \( b=2 \), then the solution must be either
$$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]
#+end_example

renders to:

If $a^2=b$ and \( b=2 \), then the solution must be either
$$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]

(Note that the last two equations show up on their own lines.)
** Equations with (r), (c), ..                                    :@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: equations-with-r-c
:END:
#+begin_description
Test to check that &reg;, &copy; and &trade; don't get interpreted
within equations.
#+end_description
{{{oxhugoissue(104)}}}

Below, =(r)= or =(R)= should not get converted to &reg;, =(c)= or
=(C)= should not get converted to &copy;, and =(tm)= or =(TM)= should
not get converted to &trade;:

- $(r)$ $(R)$
- $(c)$ $(C)$
- $(tm)$ $(TM)$


- \( (r) \) \( (R) \)
- \( (c) \) \( (C) \)
- \( (tm) \) \( (TM) \)

Same as above but in /Block Math equations/:

$$ (r) (R) $$
$$ (c) (C) $$
$$ (tm) (TM) $$

\[ (r) (R) \]
\[ (c) (C) \]
\[ (tm) (TM) \]
** Indented equations block                                        :indented:
:PROPERTIES:
:EXPORT_FILE_NAME: indented-equations
:END:
#+begin_description
Testing equations with mathjax --- indented or not.
#+end_description
*** No indentation
\begin{equation}
\label{eq:1}
C = W\log_{2} (1+\mathrm{SNR})
\end{equation}
*** With indentation
{{{oxhugoissue(128)}}}

    \begin{equation}
    \label{eq:2}
    C = W\log_{2} (1+\mathrm{SNR})
    \end{equation}

Above equation (/{{{latex}}} environment/) is the same as the first
one, but:
- It is indented in the Org source.

  /This test verifies that the indentation is auto-removed in the
  exported Markdown file./
- It has a different label (=\label{eq:2}= instead of =\label{eq:1}=);
  Mathjax *requires the equation labels to be unique*.
** Blackfriday-specific escaping in equations :escaping:@upstream:blackfriday:
:PROPERTIES:
:EXPORT_FILE_NAME: equations-bf-escaping
:END:
#+begin_description
Test to check that the backslashes are correctly escaped.
#+end_description
{{{oxhugoissue(138)}}}
*** =\|= → =\\|=
$$
C(w,b) = \frac{1}{2n} \sum_x{{\|y(x)-a\|}^2}
$$
*** =\\= at EOL → =\\\\\\=
\begin{align}
a^1  &= x \\
a^2  &=  σ(W^2a^1 + b^2) \\
a^3  &=  σ(W^3a^2 + b^3) \\
⋯ \\
a^L  &= σ(W^La^{L-1} + b^L) \\
y  &= a^L
\end{align}
**** Same as above, but without space before the =\\= at EOL
\begin{align}
a^1  &= x\\
a^2  &=  σ(W^2a^1 + b^2)\\
a^3  &=  σ(W^3a^2 + b^3)\\
⋯\\
a^L  &= σ(W^La^{L-1} + b^L)\\
y  &= a^L
\end{align}
*** =\{= → =\\{=, =\}= → =\\}=
{{{oxhugoissue(258)}}}

\begin{equation}
\phi_j(x) = \mathrm{exp}\left\{ - \frac{(x - \mu_j)^2}{2s^2} \right\}
\end{equation}
*** ~x <0 \\~
{{{oxhugoissue(348)}}}

\begin{equation}
\begin{cases}
u_t = ku_{xx} \\
u(x,0) = T_1 , & x <0 \\
u(x,0) = T_2 , & x > 0
\end{cases}
\end{equation}
*** ~[ .. ]( .. )~ in a LaTeX equation
{{{oxhugoissue(349)}}}

In the below equation, without the escaping hack, the Markdown parser
gets fooled into thinking that ~[ e^{at} \right](z)~ is a Markdown
link!

\begin{equation}
\mathcal{L}\left[ e^{at} \right](z) = \frac{1}{z-a}
\end{equation}
* Lists                                                               :lists:
** List following a list
:PROPERTIES:
:EXPORT_FILE_NAME: list-following-a-list
:EXPORT_DATE: 2017-07-31
:END:
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./ -- [[https://stackoverflow.com/a/8964494/1219634][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.
*** Unordered list following an unordered list
- foo1
- foo2


+ bar1
+ bar2
*** Unordered list following an ordered list
1. foo3
2. foo4


- bar3
- bar4
*** Ordered list following an unordered list
- foo5
- foo6


1. bar5
2. bar6
*** Ordered list following an ordered list
1. foo1
2. foo2


1. bar1
2. bar2
*** Description list following an ordered list
- foo1
- foo2


- bar1 :: description
- bar2 :: description
** Nested lists                                                   :@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: nested-lists
:EXPORT_DATE: 2017-07-31
:END:
+ L1 -- foo1
+ L1 -- foo2
  - L2 -- bar1
  - L2 -- bar2
    + L3 -- baz1
    + L3 -- baz2
      - L4 -- zoo1
      - L4 -- zoo2
        1. L5 -- numbered1
        2. L5 -- numbered2
      - L4 -- zoo1
      - L4 -- zoo2
    + L3 -- baz1
    + L3 -- baz2
  - L2 -- bar1
  - L2 -- bar2
+ L1 -- foo1
+ L1 -- foo2
*** Unordered list inside descriptive list
- bar1 :: description for bar1
  - foo1
  - foo2
- bar2 :: description for bar2
  - foo3
  - foo4
*** Descriptive list inside unordered list
*Seems like Blackfriday style descriptive list syntax does not work
when that list is nested in other lists.*

So in that case, switch back to the descriptive list syntax used in
=ox-md=.

-----

- foo1
  - bar1 :: description for bar1
  - bar2 :: description for bar2
- foo2
  - bar3 :: description for bar3
  - bar4 :: description for bar4
** Paragraphs in lists                                            :paragraph:
:PROPERTIES:
:EXPORT_FILE_NAME: paragraphs-in-lists
:END:
- Bullet lists can have paragraphs or block elements within them.

  Just indent the content to be even with the text of the bullet
  point, rather than the bullet itself.

  #+begin_src shell
  ls -l
  #+end_src
- Here's the second bullet item.

  Paragraph 1 in second bullet.

  Paragraph 2 in second bullet.

Paragraph outside the list.
** Force ordered list numbering                              :custom_counter:
:PROPERTIES:
:EXPORT_DATE: 2017-08-01
:EXPORT_FILE_NAME: force-ordered-list-numbering
:END:
Ordered lists with custom counter.

1. This will be 1.
1. This will be 2.


1. [@10] This will be 10!
1. This will be 11.


1. [@17] This will be 17!
1. This will be 18.
1. [@123] This will be 123!
1. This will be 124.


1. This will be 1 again.
1. This will be 2.

Another example:

1. This will be 1.
1. [@3] This will be 3!
1. [@7] This will be 7!
1. [@100] This will be 100!

See [[https://orgmode.org/manual/Plain-lists.html][(org) Plain lists]] to read more about plain lists in Org.
** Checklist
:PROPERTIES:
:EXPORT_FILE_NAME: checklist
:EXPORT_DATE: 2017-08-02
:EXPORT_HUGO_BLACKFRIDAY: :fractions false
:END:
This is a check-list:
*** Checklist 1 [60%]
Checklist showing progress in percentage.

- [ ] Task 1
- [X] Task 2
- [X] Task 3
- [ ] Task 4
- [X] Task 5
*** Checklist 2 [2/5]
Checklist showing progress in ratio.

- [ ] Task 1
- [ ] Task 2
- [X] Task 3
- [ ] Task 4
- [X] Task 5
** Plain lists with ATTR_HTML         :attr___html:attr___css:custom_counter:
:PROPERTIES:
:EXPORT_FILE_NAME: lists-with-attr-html
:END:
*** Unordered lists
#+attr_html: :class red-text
#+attr_css: :color red
- Red list item 1
- Red list item 2

#+attr_html: :class green-text
#+attr_css: :color green
- Green list item 1
- Green list item 2
*** Ordered lists
#+attr_html: :class green-text
1. Green ordered list item 1
2. Green ordered list item 2

/The =green-text= style is defined in the list above this one./
**** Ordered list with custom counter
#+attr_html: :class blue-text
#+attr_css: :color blue
1. Blue list item 1
2. Blue list item 2
3. [@10]Blue list item 10
*** Definition/descriptive lists
#+attr_html: :class red-text
- Defn A :: Something A in red
- Defn B :: Something B in red

/The =red-text= style is defined in the first list above./
** Source blocks, example blocks and lists
*** Source block following a list                       :src_block:@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: src-block-following-a-list
:END:
#+begin_description
Test to verify rendering of a source block immediately following a
plain list, and even a list following a heading following a source
block.
#+end_description

- [[https://discourse.gohugo.io/t/rendering-code-blocks-properly-from-md-files/19126][Ref 1]]
- [[https://discourse.gohugo.io/t/possible-regression-in-v0-55-5-regarding-lists-containing-code-blocks/18502/4?u=kaushalmodi][Ref 2]]
- {{{bfissue(556)}}}


- list item 1
- list item 2
#+begin_src nim
echo "hello"
#+end_src
- another list item 1
- another list item 2
**** A heading in post
#+begin_src nim
echo "hello again"
#+end_src
*** Example block following a list                  :example_block:@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: example-block-following-a-list
:END:
#+begin_description
Test to verify rendering of a example block immediately following a
plain list, and even a list following a heading following a example
block.
#+end_description

- [[https://discourse.gohugo.io/t/rendering-code-blocks-properly-from-md-files/19126][Ref 1]]
- [[https://discourse.gohugo.io/t/possible-regression-in-v0-55-5-regarding-lists-containing-code-blocks/18502/4?u=kaushalmodi][Ref 2]]
- {{{bfissue(556)}}}


- list item 1
- list item 2
#+begin_example
something in example block
#+end_example
- another list item 1
- another list item 2
**** A heading in post
#+begin_example
another example block
#+end_example
*** Source and example blocks in lists              :src_block:example_block:
:PROPERTIES:
:EXPORT_FILE_NAME: src-and-example-blocks-in-lists
:END:
#+begin_description
Test to verify rendering of source and example blocks in lists.
#+end_description

[[https://discourse.gohugo.io/t/blackfriday-not-handling-lists-and-code-blocks-the-right-way/19932][Ref]]

- list item 1
  #+begin_src nim
  echo "hello from list item 1"
  #+end_src
  - list item 1.1
    #+begin_example
    echo "hello from list item 1.1"
    #+end_example
  -
    #+begin_example
    echo "hello from list item 1.2"
    echo "there's not text before this example block in this list item"
    #+end_example
    - list item 1.2.1
      #+begin_src nim
      echo "hello from list item 1.2.1"
      #+end_src
    -
      #+begin_src nim
      echo "hello from list item 1.2.2"
      echo "there's not text before this src block in this list item"
      #+end_src
      - list item 1.2.2.1
        #+begin_example
        echo "hello from list item 1.2.2.1"
        #+end_example
-
  #+begin_src nim
  echo "hello from list item 2"
  echo "there's not text before this src block in this list item"
  #+end_src
- list item 3
  #+begin_example
  echo "hello from list item 3"
  #+end_example
* Quotes                                                             :quotes:
** Consecutive quotes
:PROPERTIES:
:EXPORT_FILE_NAME: consecutive-quotes
:EXPORT_DATE: 2017-08-01
:END:
Some text.
#+begin_quote
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.
#+end_quote
#+begin_quote
Quote 2. This is a short quote.
#+end_quote
#+begin_quote
Quote 3. This is a multi-paragraph quote.

This is the second paragraph.
#+end_quote
Some other text.
** Example block inside quote block
:PROPERTIES:
:EXPORT_FILE_NAME: example-block-inside-quote-block
:END:
Some text.
#+begin_quote
Some quoted text.

    #+begin_example
    (some-example)
    #+end_example
#+end_quote
Some other text.
** Multiple example blocks inside quote block
:PROPERTIES:
:EXPORT_FILE_NAME: multiple-example-blocks-inside-quote-block
:END:
Some text.
#+begin_quote
Some quoted text.

    #+begin_example
    (some-example)
    #+end_example
    #+begin_example
    (some-other-example)
    #+end_example
#+end_quote
Some other text.
** Source block inside quote block, followed by another source block outside :backticks:src_block:@upstream:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-inside-quote-block-and-another-source-block
:END:
{{{bfissue(407)}}}

Some text.
#+include: "./all-posts.org::#quote-blk-with-src-block--followed-by-src" :only-contents t
*1* Some text.
#+include: "./all-posts.org::#quote-blk-with-src-block--followed-by-src" :only-contents t
*2* Some text.
#+include: "./all-posts.org::#quote-blk-with-src-block--followed-by-src" :only-contents t
*3* Some text.
#+include: "./all-posts.org::#quote-blk-with-src-block--followed-by-src" :only-contents t
*4* Some text.
#+include: "./all-posts.org::#quote-blk-with-src-block--followed-by-src" :only-contents t
*5* Some text.
#+include: "./all-posts.org::#quote-blk-with-src-block--followed-by-src" :only-contents t
Some other text.
** Example blocks inside quote block, followed by another example block outside
:PROPERTIES:
:EXPORT_FILE_NAME: example-blocks-inside-quote-block-and-another-example-block
:END:
[[https://github.com/russross/blackfriday/issues/407][Blackfriday Issue # 407]]

Some text.
#+begin_quote
Some quoted text.
    #+begin_example
    (some-example)
    #+end_example
    #+begin_example
    (some-other-example)
    #+end_example
#+end_quote

#+begin_example
(yet-another-example)
#+end_example
Some other text.
** Source block, followed by a quote block containing another source block
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-followed-by-a-quote-block-containing-another-source-block
:END:
Some text.
#+begin_src emacs-lisp
(message "hello")
#+end_src
#+begin_quote
Some quoted text.
    #+begin_src emacs-lisp
    (message "hello again")
    #+end_src
#+end_quote
Some other text.
** Example block with escaped Org syntax inside quote block
:PROPERTIES:
:EXPORT_FILE_NAME: example-block-with-escaped-org-inside-quote-block
:END:
Some text.
#+begin_quote
Some quoted text.

    #+begin_example
    ,#+name: some_example
    (some-example)
    #+end_example
#+end_quote
Some other text.
** Quote blocks with ATTR_HTML                       :attr___html:attr___css:
:PROPERTIES:
:EXPORT_FILE_NAME: quote-blocks-with-attr-html
:END:
Some text.

#+attr_html: :class red-text
#+attr_css: :color red
#+begin_quote
This is a red quote.
#+end_quote

Some more text.
** Quote blocks in numbered lists                                     :lists:
:PROPERTIES:
:EXPORT_FILE_NAME: quote-blocks-in-numbered-lists
:END:
#+begin_description
Testing quote blocks in numbered lists, just because this came up on
[[https://discourse.gohugo.io/t/put-a-blockquote-into-a-numbered-list/19339/1][Hugo Discourse]].
#+end_description
1. List item 1

   Text before quote block.
   #+begin_quote
   Quote block in list item 1
   #+end_quote
   Text after quote block.
2. List item 2

   Text before quote block.
   #+begin_quote
   Quote block in list item 2
   #+end_quote
   Text after quote block.
3. List item 3

   Text before quote block.
   #+begin_quote
   Quote block in list item 3
   #+end_quote
   Text after quote block.
* Verse                                                               :verse:
** One verse
:PROPERTIES:
:EXPORT_DATE: 2017-08-01
:EXPORT_FILE_NAME: one-verse
:END:
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 -- [[https://orgmode.org/manual/Paragraphs.html][Reference]].
#+begin_verse
Great clouds overhead
Tiny black birds rise and fall
Snow covers Emacs

    -- AlexSchroeder
#+end_verse
** Consecutive verses
:PROPERTIES:
:EXPORT_DATE: 2017-08-01
:EXPORT_FILE_NAME: consecutive-verses
:END:
#+begin_verse
Tyger Tyger, burning bright,
In the forests of the night;
What immortal hand or eye,
Could frame thy fearful symmetry?

In what distant deeps or skies.
Burnt the fire of thine eyes?
On what wings dare he aspire?
What the hand, dare seize the fire?

   -- "The Tyger" /by/ William Blake
#+end_verse
#+begin_verse
Some parts can be *bold*
  Some can be =monospace=
    Some can be /italic/ too.
#+end_verse
#+begin_verse
What is this life if, full of care,
We have no time to stand and stare.

No time to stand beneath the boughs
And stare as long as sheep or cows.

No time to see, when woods we pass,
Where squirrels hide their nuts in grass.

   -- "Leisure" /by/ William Henry Davis
#+end_verse
** Verse for indentation
:PROPERTIES:
:EXPORT_FILE_NAME: verse-for-indentation
:END:
Some text before indented text.
#+begin_verse
>    Text indented by 4 spaces
#+end_verse
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 examples
- More indentation than in the above example:
  #+begin_verse
  >        Text indented by 8 spaces
  #+end_verse
- Leading blank line followed by indented text:
  #+begin_verse

  >    Text indented by 4 spaces
  #+end_verse
- Indented text followed by a trailing blank line:
  #+begin_verse
  >    Text indented by 4 spaces

  #+end_verse
- Using tab characters for indentation; each tab character still
  constitutes for one =&nbsp;= in HTML.
  #+begin_verse
  >				Text indented by 4 tab characters
  #+end_verse
*** Corner cases
Only the *first* =>= character immediately following spaces and empty
lines will be removed:
#+begin_verse

>Line 1 above was empty. So the first =>= seen on this line is removed.
Line 3 had no =>= char.
> ← See that this =>= on line 4 is retained even at the beginning of the line.
Line 5 has this > charcter in-between and is retained.
#+end_verse

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.
#+begin_verse

>>Line 1 above was empty. So *only* the first =>= seen on this line is removed.
Line 3 had no =>= char.
> ← See that this =>= on line 4 is retained even at the beginning of the line.
Line 5 has this > charcter in-between and is retained.
#+end_verse
* Org Special Blocks                                          :special_block:
** Special Blocks
:PROPERTIES:
:EXPORT_FILE_NAME: special-blocks
:END:
*** HTML5 Element Blocks
**** Block without NAME, class or id
#+begin_article
This is /an article/.
#+end_article
**** Block with NAME
#+name: Aside-A
#+begin_aside
/Some/ *text* --- 1

| a | b | c |
| d | e | f |
#+end_aside
**** Block with class and id
#+attr_html: :class my-section :id section-a
#+begin_section
/Some/ *text* --- 2

| g | h | i |
| j | k | l |
#+end_section
**** An inline HTML5 element
Unmarked.
#+begin_mark
/Some/ *marked* text --- 2.5.
#+end_mark
Unmarked again.
*** DIV-wrapped Blocks
**** DIV without NAME, class or id
#+begin_something
This is /some text/ wrapped in a =div= block with class =something=.
#+end_something
**** DIV with NAME
#+name: Foo-A
#+begin_foo
/Some/ *text* --- 3

| m | n | o |
| p | q | r |
#+end_foo
**** DIV with class and id
#+attr_html: :class my-bar :id bar-a
#+begin_bar
/Some/ *text* --- 4

| s | t | u |
| v | w | x |
#+end_bar
** Empty Special Block                                                :empty:
:PROPERTIES:
:EXPORT_FILE_NAME: special-block-empty
:END:
#+begin_description
This post contains an empty Org Special Block.
#+end_description

The empty Org Special Block is not exported at all.

#+begin_foo
#+end_foo
** Special Block with just white space                           :whitespace:
:PROPERTIES:
:EXPORT_FILE_NAME: special-block-whitespace
:END:
#+begin_description
This post contains an Org Special Block with just white space (blank
line).
#+end_description

#+begin_foo

#+end_foo
** Details and summary                           :details:summary:disclosure:
:PROPERTIES:
:EXPORT_FILE_NAME: details-and-summary
:END:
#+begin_description
Details disclosure elements [[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details][~<details>~]] and ~<summary>~.
#+end_description

These can be conveniently created using the Org Special Block
~#+begin_details~ .. ~#+end_details~.

The summaries in these "details" Org Special blocks should be wrapped
in a "summary" Org Special block ~#+begin_summary~ .. ~#+end_summary~.
*** Closed details disclosure (default)
**** Summary + Details
#+begin_details
#+begin_summary
#+include: "./all-posts.org::#details-disclosure-summary" :only-contents t
#+end_summary
#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
#+end_details
**** No summary, only details
In the situation where the summary divider is absent i.e. when user
hasn't provided a summary, the browser will use a default summary
string (usually "Details").
#+begin_details
#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
#+end_details
**** Only summary, no details
In this case where only the "summary" exists, the browser will still
render the collapsing triangle. But nothing will show up when you
uncollapse it.. /as there are no details/.
#+begin_details
#+begin_summary
#+include: "./all-posts.org::#details-disclosure-summary" :only-contents t
#+end_summary
#+end_details
**** Details containing only code block
#+begin_details
#+begin_summary
This is *Summary*.
#+end_summary
#+begin_src emacs-lisp
(message "This is in details")
#+end_src
#+end_details
**** Summary containing only code block
#+begin_details
#+begin_summary
#+begin_src emacs-lisp
(message "This is in summary")
#+end_src
#+end_summary
Here are the /details/. This is obviously a pathological test case.
#+end_details
*** Open by default disclosure widget
The details disclosures are closed by default, add ~#+attr_html: :open
t~ right below the details special block to have the disclosures open
by default.
**** Summary + Details (Open)
#+attr_html: :open t
#+begin_details
#+begin_summary
#+include: "./all-posts.org::#details-disclosure-summary" :only-contents t
#+end_summary
#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
#+end_details
**** No summary, only details (Open)
#+attr_html: :open t
#+begin_details
#+include: "./all-posts.org::#details-disclosure-details" :only-contents t
#+end_details
**** Only summary, no details (Open)
#+attr_html: :open t
#+begin_details
#+begin_summary
#+include: "./all-posts.org::#details-disclosure-summary" :only-contents t
#+end_summary
#+end_details
*** Other attributes along with ~open~ attribute set to ~t~
Test that other attributes, if present along with ~:open t~, are also retained.
#+attr_html: :open t :class foo
#+begin_details
#+begin_summary
This is *summary*.
#+end_summary
Here are the /details/.
#+end_details
*** Value of ~open~ attribute other than ~t~
If the ~open~ attribute is set to any other value than ~t~, it won't
be inserted in the ~details~ element.
#+attr_html: :open nil :class foo
#+begin_details
#+begin_summary
This is *summary*.
#+end_summary
Here are the /details/.
#+end_details
* Shortcodes                                                      :shortcode:
** Alert CSS                                                       :noexport:
*** Common CSS
:PROPERTIES:
:CUSTOM_ID: alert-common-css
:END:
#+begin_export html
<style>
 .alert {
     padding: 15px;
     margin-bottom: 20px;
     border: 1px solid transparent;
     border-radius: 4px;
 }
 div.alert {
     border-radius: 10px;
     margin-bottom: 1rem;
 }

 div.alert p {
     position: relative;
     display: block;
     font-size: 1rem;
     margin-left: 2rem;
     margin-top: 0;
     margin-bottom: 0;
 }

 div.alert a {
     color: rgba(255,255,255,0.9);
     text-decoration: none;
     border-bottom: solid 1px #e4e4e4;
     transition: color 0.2s ease-in-out, border-color 0.2s ease-in-out;
 }

 div.alert a:hover {
     border-bottom-color: transparent;
     color: rgba(255,255,255,0.5) !important;
 }

 .alert-note {
     color: #fff;
     background-color: #03A9F4; /* Material LightBlue500 */
     border-color: #bce8f1;
 }

 .alert-warning {
     color: #fff;
     background-color: #f44336; /* Material Red500 */
     border-color: #ebccd1;
 }
</style>
#+end_export
*** Original icon prefixing code
:PROPERTIES:
:CUSTOM_ID: alert-original-icon-prefixing-css
:END:
#+begin_export html
<style>
 div.alert p:first-child::before {
     position: absolute;
     top: -0.5rem;
     left: -2rem;
     font-family: 'FontAwesome';
     font-size: 1.5rem;
     color: #fff;
     /* content: '\f05a'; */
     content: '🛈';
     width: 1.5rem;
     text-align: center;
 }

 div.alert-warning p:first-child:before {
     /* content: '\f071'; */
     content: '⚠';
 }
</style>
#+end_export
*** Modified icon prefixing code
:PROPERTIES:
:CUSTOM_ID: alert-modified-icon-prefixing-css
:END:
#+begin_export html
<style>
 /* Because of the empty div hack, the first paragraph will be the
    second child in the div. So use "p:nth-child(2)" instead of the
    original "p:first-child". */
 div.alert p:nth-child(2)::before {
     position: absolute;
     top: -0.5rem;
     left: -2rem;
     font-family: 'FontAwesome';
     font-size: 1.5rem;
     color: #fff;
     /* content: '\f05a'; */
     content: '🛈';
     width: 1.5rem;
     text-align: center;
 }

 /* Because of the empty div hack, the first paragraph will be the
    second child in the div. So use "p:nth-child(2)" instead of the
    original "p:first-child". */
 div.alert-warning p:nth-child(2):before {
     /* content: '\f071'; */
     content: '⚠';
 }
</style>
#+end_export
** Alert Shortcode Lookalike                :alert:special_block:attr___html:
:PROPERTIES:
:EXPORT_FILE_NAME: alert-short-code-lookalike
:END:

{{{oxhugoissue(119)}}}

Below doesn't export to an =alert= shortcode, but the exported
Markdown contains HTML that resembles the [[https://github.com/gcushen/hugo-academic/blob/master/layouts/shortcodes/alert.html][shortcode code]] (Courtesy:
[[https://github.com/gcushen/hugo-academic][=hugo-academic= theme]]):

#+begin_src html
<div class="alert alert-{{ .Get 0 }}">
  {{ .Inner }}
</div>
#+end_src

There are few days to mimic that.
*** CSS
[[https://github.com/gcushen/hugo-academic/blob/66b71fa2f6a41f26d6c3b202fef212fab151112e/layouts/partials/css/academic.css#L1370-L1426][Source for *alert* CSS]]

- Note 1 :: The =ox-hugo= test site is not using *FontAwesome*, so
            using the unicode symbols 🛈 and ⚠ instead.
- Note 2 :: Also, due to the limitation that Markdown text cannot be
            simply wrapped in =div=, a hack is used, that requires
            using an empty =div= pair. So that requires overriding a
            bit of the default CSS from the theme.
**** CSS Override for Academic theme
In summary, these overrides over the theme CSS would suffice:

#+begin_src css
/* Because of the empty div hack, the first paragraph will be the
   second child in the div. So use "p:nth-child(2)" instead of the
   original "p:first-child". */
div.alert p:nth-child(2)::before {
    position: absolute;
    top: -0.5rem;
    left: -2rem;
    font-family: 'FontAwesome';
    font-size: 1.5rem;
    color: #fff;
    content: '\f05a';
    /* Use below if not using FontAwesome */
    /* content: '🛈'; */
    width: 1.5rem;
    text-align: center;
}

div.alert-warning p:nth-child(2):before {
    content: '\f071';
    /* Use below if not using FontAwesome */
    /* content: '⚠'; */
}
#+end_src

#+include: "./all-posts.org::#alert-common-css" :only-contents t
#+include: "./all-posts.org::#alert-modified-icon-prefixing-css" :only-contents t
*** Alert using Special Block
#+attr_html: :class alert-note
#+begin_alert
Here's a tip or note.

This can be multi-paragraph too.
#+end_alert

#+attr_html: :class alert-warning
#+begin_alert
Here's a warning!

This can be multi-paragraph too.
#+end_alert
*** Alert using only =#+attr_html=
This will work only if the message is a single paragraph.

#+attr_html: :class alert alert-note
Here's a tip or note.

#+attr_html: :class alert alert-warning
Here's a warning!
** Paired Shortcodes using special blocks              :paired:special_block:
*** Paired Shortcodes using special blocks (No Arguments)      :no_arguments:
:PROPERTIES:
:EXPORT_FILE_NAME: paired-shortcodes-special-blocks-no-arguments
:EXPORT_HUGO_PAIRED_SHORTCODES: %mdshortcode myshortcode
:END:
Test case for feature requested in {{{oxhugoissue(119)}}}.
**** Paired markdown shortcode
#+begin_mdshortcode
Content *with* /emphasis/ characters is rendered.

The HTML <b>markup</b> will also get rendered.
#+end_mdshortcode

This will export as:

#+begin_src md
{{% mdshortcode %}} Content rendered as Markdown {{% /mdshortcode %}}
#+end_src
**** Paired non-markdown (default) shortcode
#+begin_myshortcode
Content is rendered <b>like HTML</b>. The Markdown /emphasis/
characters are !! NOT !! rendered.

So a blank line before this sentence in the Markdown source will
<b>not</b> result in a new paragraph in HTML. <p>But this will be a
new paragraph as it is wrapped in HTML <code>&lt;p&gt;</code>
tags.</p>
#+end_myshortcode

This will export as:

#+begin_src md
{{< myshortcode >}} Content NOT rendered as Markdown {{< /myshortcode >}}
#+end_src
**** Not a recognized paired shortcode
#+begin_foo
Content *with* Markdown /emphasis/ characters is rendered fine in the
default Special Blocks.
#+end_foo

This will export as [[/posts/special-blocks][Special Blocks]] --- either wrapped with =<div>=
tags or HTML5-recognized tags.
*** Paired shortcodes using special blocks (Positional Arguments) :positional:arguments:
:PROPERTIES:
:EXPORT_FILE_NAME: paired-shortcodes-special-blocks-positional-arguments
:EXPORT_HUGO_PAIRED_SHORTCODES: %alert myshortcode-pos
:END:
Test case for feature requested in {{{oxhugoissue(119)}}}.
**** Paired markdown shortcode
The =alert= shortcode takes 1 positional argument.

#+include: "./all-posts.org::#alert-common-css" :only-contents t
#+include: "./all-posts.org::#alert-original-icon-prefixing-css" :only-contents t

#+attr_shortcode: note
#+begin_alert
Content *with* /emphasis/ characters is rendered.

The HTML <b>markup</b> will also get rendered.
#+end_alert

-----

Below is the about same as above, except that =warning= attribute
(argument to the exported shortcode) is used instead of =note=.

#+attr_shortcode: warning
#+begin_alert
Content *with* /emphasis/ characters is rendered.

The HTML <b>markup</b> will also get rendered.
#+end_alert
**** Paired non-markdown (default) shortcode
The =myshortcode-pos= takes 2 positional arguments. In the below
example, the double-quoted ="foo bar"= will be the /first/ argument,
and ="zoo"= will be the /second/.

#+attr_shortcode: "foo bar" zoo
#+begin_myshortcode-pos
Content is rendered <b>like HTML</b>. The Markdown /emphasis/
characters are !! NOT !! rendered.
#+end_myshortcode-pos
*** Paired shortcodes using special blocks (Named Arguments) :arguments:named:
:PROPERTIES:
:EXPORT_FILE_NAME: paired-shortcodes-special-blocks-named-arguments
:EXPORT_HUGO_PAIRED_SHORTCODES: %mdshortcode-named myshortcode-named
:END:
Test case for feature requested in {{{oxhugoissue(119)}}}.
**** Paired markdown shortcode
In the below example, ="foo bar"= will be the /arg1/ argument, and
="color: red; text-align: center;"= will be the /arg2/ argument.

#+attr_shortcode: :arg1 foo bar :arg2 color: red; text-align: center;
#+begin_mdshortcode-named
Content *with* /emphasis/ characters is rendered.

The HTML <b>markup</b> will also get rendered.
#+end_mdshortcode-named
**** Paired non-markdown (default) shortcode
In the below example, ="foo"= will be the /arg1/ argument, and
="color:green;"= will be the /arg2/ argument.

#+attr_shortcode: :arg1 foo :arg2 color:green;
#+begin_myshortcode-named
Content is rendered <b>like HTML</b>. The Markdown /emphasis/
characters are !! NOT !! rendered.
#+end_myshortcode-named
** Using Org macros in lieu of Hugo shortcodes
:PROPERTIES:
:EXPORT_FILE_NAME: using-org-macros-in-lieu-of-hugo-shortcodes
:END:
#+begin_description
Using Org macros in place of Hugo shortcodes to make the Org content
reusable across more export backends.
#+end_description
{{{oxhugoissue(303)}}}

The ~youtube~ Org macros used here kind of mimics the Hugo shortcode
[[https://github.com/gohugoio/hugo/blob/00297085db48cbb7949c9867012f6df38817fc29/tpl/tplimpl/embedded/templates/shortcodes/youtube.html][*youtube*]].

{{{youtube(v_jDFgS2AqE)}}}
* Paragraphs                                                      :paragraph:
** Paragraphs with ATTR_HTML                         :attr___html:attr___css:
:PROPERTIES:
:EXPORT_FILE_NAME: paragraphs-with-attr-html
:END:
Regular text.

#+attr_html: :class red-text
#+attr_css: :color red
Red text.

Regular text.

#+attr_html: :class green-text
#+attr_css: :color green
Green text.

Regular text.
* Org TODO keywords                                                    :todo:
** Post with a TODO heading
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-todo
:END:
*** Heading 1
Some text.
*** TODO Heading 2
Some text.
** Post with a DONE heading
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-done
:END:
*** Heading 1
Some text.
*** DONE Heading 2
CLOSED: [2017-08-09 Wed 16:15]
Some text.
** Org TODO keywords with double-underscores       :double_underscores:space:
:PROPERTIES:
:EXPORT_FILE_NAME: org-todo-kwd-with-double-underscores
:END:
#+begin_description
This feature that replaces double-underscores in Org TODO keywords
with spaces was added in {{{commit(7691f0453b)}}}.
#+end_description
*** TEST__TODO This heading's TODO kwd should read as "TEST TODO"
*** TEST__DONE This heading's TODO kwd should read as "TEST DONE"
** Deeply nested Org TODO headings                                   :nested:
*** Reused test body
:PROPERTIES:
:CUSTOM_ID: deeply-nested-todo-headings
:END:
{{{oxhugoissue(250)}}}
**** TODO Level 1
***** TODO Level 2
****** TODO Level 3
******* TODO Level 4
******** TODO Level 5
********* TODO Level 6
********** TODO Level 7
*** Deeply nested Org TODO headings -- Default heading level
:PROPERTIES:
:EXPORT_FILE_NAME: deeply-nested-org-todo-headings--default-h
:END:
#+include: "./all-posts.org::#deeply-nested-todo-headings" :only-contents t
*** Deeply nested Org TODO headings -- h1
:PROPERTIES:
:EXPORT_FILE_NAME: deeply-nested-org-todo-headings--h1
:EXPORT_OPTIONS: h:1
:END:
#+include: "./all-posts.org::#deeply-nested-todo-headings" :only-contents t
*** Deeply nested Org TODO headings -- h2
:PROPERTIES:
:EXPORT_FILE_NAME: deeply-nested-org-todo-headings--h2
:EXPORT_OPTIONS: h:2
:END:
#+include: "./all-posts.org::#deeply-nested-todo-headings" :only-contents t
*** Deeply nested Org TODO headings -- h5
:PROPERTIES:
:EXPORT_FILE_NAME: deeply-nested-org-todo-headings--h5
:EXPORT_OPTIONS: h:5
:END:
#+include: "./all-posts.org::#deeply-nested-todo-headings" :only-contents t
*** Deeply nested Org TODO headings -- h6
:PROPERTIES:
:EXPORT_FILE_NAME: deeply-nested-org-todo-headings--h6
:EXPORT_OPTIONS: h:6
:END:
#+include: "./all-posts.org::#deeply-nested-todo-headings" :only-contents t
*** Deeply nested Org TODO headings -- h6, Offset 0
:PROPERTIES:
:EXPORT_FILE_NAME: deeply-nested-org-todo-headings--h6--offset0
:EXPORT_OPTIONS: h:6
:EXPORT_HUGO_LEVEL_OFFSET: 0
:END:
#+include: "./all-posts.org::#deeply-nested-todo-headings" :only-contents t
* Level Offset                                                 :level_offset:
** Default level offset
:PROPERTIES:
:EXPORT_FILE_NAME: level-offset-default
:END:
#+begin_description
Test for multiple levels of headings that could even go beyond the max
~<h6>~ heading level supported by HTML.
#+end_description
*** Heading 1 Level 1
**** Heading 1 Level 2
***** Heading 1 Level 3
****** Heading 1 Level 4
******* Heading 1 Level 5
******** Heading 1 Level 6
********* Heading 1 Level 7
********** Heading 1 Level 8
*** Heading 2 Level 1
H2 L1 Content
**** Heading 2 Level 2
H2 L2 Content

- H2 L2 item 1
- H2 L2 item 2
***** Heading 2 Level 3
- H2 L3 item 1
- H2 L3 item 2

H2 L3 Content
****** Heading 2 Level 4
H2 L4 Content

- H2 L4 item 1
- H2 L4 item 2

H2 L4 Content
******* Heading 2 Level 5
H2 L5 Content
******** Heading 2 Level 6
H2 L6 Content

- H2 L6 item 1
- H2 L6 item 2
********* Heading 2 Level 7
- H2 L7 item 1
- H2 L7 item 2

H2 L7 Content
********** Heading 2 Level 8
H2 L8 Content

- H2 L8 item 1
- H2 L8 item 2

H2 L8 Content
*** Heading 3 Level 1
** Level offset unset
:PROPERTIES:
:EXPORT_FILE_NAME: level-offset-unset
:EXPORT_HUGO_LEVEL_OFFSET:
:END:
Setting =:EXPORT_HUGO_LEVEL_OFFSET:= is same as setting
=:EXPORT_HUGO_LEVEL_OFFSET: 0=.
*** Heading 1
**** Heading 1.1
*** Heading 2
** Level offset of 0
:PROPERTIES:
:EXPORT_FILE_NAME: level-offset-0
:EXPORT_HUGO_LEVEL_OFFSET: 0
:END:
*** Heading 1
**** Heading 1.1
*** Heading 2
** Level offset of 1
:PROPERTIES:
:EXPORT_FILE_NAME: level-offset-1
:EXPORT_HUGO_LEVEL_OFFSET: 1
:END:
*** Heading 1
**** Heading 1.1
*** Heading 2
** Level offset of 2
:PROPERTIES:
:EXPORT_FILE_NAME: level-offset-2
:EXPORT_HUGO_LEVEL_OFFSET: 2
:END:
*** Heading 1
**** Heading 1.1
*** Heading 2
* Blackfriday Options                                           :blackfriday:
** Fractions
*** Fraction Table
:PROPERTIES:
:CUSTOM_ID: fraction-table
:END:
|------+------+------+------+------+------+------+------+------+-------+-------+-------+-------|
| /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 |
|------+------+------+------+------+------+------+------+------+-------+-------+-------+-------|
*** Blackfriday fractions false
:PROPERTIES:
:EXPORT_FILE_NAME: blackfriday-fractions-false
:EXPORT_DATE: 2017-08-02
:EXPORT_HUGO_BLACKFRIDAY: :fractions nil
:END:
A Blackfriday option can be disabled by setting the option value to
/nothing/, =nil= or =false=.

These will not be rendered as fractions:
#+include: "./all-posts.org::#fraction-table" :only-contents t

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
*** Blackfriday fractions true
:PROPERTIES:
:EXPORT_FILE_NAME: blackfriday-fractions-true
:EXPORT_DATE: 2017-08-02
:EXPORT_HUGO_BLACKFRIDAY: :fractions t
:END:
A Blackfriday option can be enabled by setting the option value to
=t= or =true=.

All of these will be rendered as fractions:
#+include: "./all-posts.org::#fraction-table" :only-contents t

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
** Extensions
*** Hard line break wrong case (TOML)                                  :toml:
:PROPERTIES:
:EXPORT_FILE_NAME: blackfriday-ext-hardlinebreak-wrong-case-toml
:EXPORT_DATE: 2017-08-02
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardlinebreak
:END:
The Blackfriday =hardLineBreak= extension is enabled here even where
user used the wrong case in the extension name:
#+begin_example
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardlinebreak
#+end_example
instead of:
#+begin_example
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardLineBreak
#+end_example

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!
:raised_hands:.

a
b
c

Above, /a/, /b/ and /c/ must appear on separate lines.
*** Hard line break (TOML)                                             :toml:
:PROPERTIES:
:EXPORT_FILE_NAME: blackfriday-ext-hardlinebreak-toml
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardLineBreak
:END:
a
b
c

Above, /a/, /b/ and /c/ must appear on separate lines.
*** Hard line break (YAML)                                             :yaml:
:PROPERTIES:
:EXPORT_FILE_NAME: blackfriday-ext-hardlinebreak-yaml
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardLineBreak
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
a
b
c

Above, /a/, /b/ and /c/ must appear on separate lines.
*** Enabling/Disabling extensions
:PROPERTIES:
:EXPORT_HUGO_BLACKFRIDAY: :smartdashes :fractions nil :plainidanchors false
:EXPORT_HUGO_BLACKFRIDAY+: :angledquotes t :hrefTargetBlank true
:EXPORT_HUGO_BLACKFRIDAY+: :extensions tabsizeeight hardlinebreak
:EXPORT_HUGO_BLACKFRIDAY+: :extensionsmask fencedcode strikethrough
:END:
**** Enabling/Disabling extensions example
:PROPERTIES:
:CUSTOM_ID: enabling-disabling-extensions-example
:END:
- Extensions enabled :: =tabSizeEight=, =hardLineBreak=
- Extensions disabled :: =fencedCode=, =strikethrough=
***** Angled quotes enabled
"this"
***** Hard line break enabled
a
b
c
***** Plain ID Anchors disabled
Check the ID for all the headings in this post's HTML. The ID's will
look something like:
#+begin_src html
<h2 id="plain-id-anchors-disabled:c94b2acd735ed6a466ef85be48bdea8c">Plain ID Anchors disabled</h2>
#+end_src
where =:c94b2acd735ed6a466ef85be48bdea8c= is the document ID.
***** Fractions disabled
2/5
***** Smart dashes disabled
a--b	c--d
***** Fenced code disabled
Below, the code block language name will show up before the code.
#+begin_src emacs-lisp
(message "Hello")
#+end_src
***** Strikethrough disabled
+not-canceled+
**** Enabling/Disabling extensions (TOML)                              :toml:
:PROPERTIES:
:EXPORT_FILE_NAME: blackfriday-ext-enabling-disabling-toml
:EXPORT_DATE: 2017-08-02
:END:
#+include: "./all-posts.org::#enabling-disabling-extensions-example" :only-contents t
**** Enabling/Disabling extensions (YAML)                              :yaml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:EXPORT_FILE_NAME: blackfriday-ext-enabling-disabling-yaml
:EXPORT_DATE: 2017-08-02
:END:
#+include: "./all-posts.org::#enabling-disabling-extensions-example" :only-contents t
* Weights                                                            :weight:
** Post Weight (Not the menu item weight)                       :page_weight:
*** Manually specified post weights                                  :manual:
**** Post with weight 123
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: 123
:EXPORT_FILE_NAME: hugo-post-weight-123
:END:
**** Post with weight 4567
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: 4567
:EXPORT_FILE_NAME: hugo-post-weight-4567
:END:
*** Auto post-weight calculation                                       :auto:
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: auto
:END:
**** Post with auto weight calc 1 (EXPORT_HUGO_WEIGHT as subtree property)
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-post-weight-1
:END:
**** Post with auto weight calc 2 (EXPORT_HUGO_WEIGHT as subtree property)
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-post-weight-2
:END:
**** Post with auto weight calc 3 (EXPORT_HUGO_WEIGHT as subtree property)
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-post-weight-3
:END:
**** Post with auto weight calc 4 (EXPORT_HUGO_WEIGHT as subtree property)
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-post-weight-4
:END:
**** Post with auto weight calc 5 (EXPORT_HUGO_WEIGHT as subtree property)
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-post-weight-5
:END:
** Taxonomy Weight (Not the post or menu item weight)       :taxonomy_weight:
*** Manually specified taxonomy weights                              :manual:
**** Taxonomy (tags) weight set 111                                    :tags:
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: :tags 111
:EXPORT_FILE_NAME: taxonomy-tags-weight-111
:END:
**** Taxonomy (categories) weight set 222                        :categories:
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: :categories 222
:EXPORT_FILE_NAME: taxonomy-categories-weight-222
:END:
**** Taxonomy weights and page weight           :tags:page_weight:categories:
***** Taxonomy weights and page weight 1
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: 77 :tags 111 :categories 999
:EXPORT_FILE_NAME: taxonomy-and-page-weights-1
:END:
If you want to specify page weight along with taxonomy weights, *and*
if you do not use the =:page= keyword before the weight value, the
page weight *must* be specified as the very first weight.
***** Taxonomy weights and page weight 2
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: :tags 111 :categories 999 :page 77
:EXPORT_FILE_NAME: taxonomy-and-page-weights-2
:END:
The page weight does not have to be specified as the very first weight
if using the =:page= keyword before the weight value.
***** Taxonomy weights and page weight 3
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: 77
:EXPORT_HUGO_WEIGHT+: :tags 111
:EXPORT_HUGO_WEIGHT+: :categories 999
:EXPORT_FILE_NAME: taxonomy-and-page-weights-3
:END:
If you want to specify page weight along with taxonomy weights, *and*
if you do not use the =:page= keyword before the weight value, the
page weight *must* be specified as the very first weight, even when
you specify the weights separately on each line.
***** Taxonomy weights and page weight 4
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: :tags 111
:EXPORT_HUGO_WEIGHT+: :page 77
:EXPORT_HUGO_WEIGHT+: :categories 999
:EXPORT_FILE_NAME: taxonomy-and-page-weights-4
:END:
The page weight does not have to be specified as the very first weight
if using the =:page= keyword before the weight value.
*** Auto taxonomy weight calculation                                   :auto:
**** Tags                                                              :tags:
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: :tags auto
:END:
***** Post with auto taxonomy (tags) weight calc 1
:PROPERTIES:
:EXPORT_FILE_NAME: taxonomy-tags-weight-auto-1
:END:
***** Post with auto taxonomy (tags) weight calc 2
:PROPERTIES:
:EXPORT_FILE_NAME: taxonomy-tags-weight-auto-2
:END:
**** Categories                                                  :categories:
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: :categories auto
:END:
***** Post with auto taxonomy (categories) weight calc 1
:PROPERTIES:
:EXPORT_FILE_NAME: taxonomy-categories-weight-auto-1
:END:
***** Post with auto taxonomy (categories) weight calc 2
:PROPERTIES:
:EXPORT_FILE_NAME: taxonomy-categories-weight-auto-2
:END:
**** Taxonomy weights and page weight           :page_weight:tags:categories:
***** Taxonomy weights and page weight (auto) 1
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: auto
:EXPORT_HUGO_WEIGHT+: :tags auto
:EXPORT_HUGO_WEIGHT+: :categories auto
:EXPORT_FILE_NAME: taxonomy-and-page-weights-auto-1
:END:
If you want to specify page weight along with taxonomy weights, *and*
if you do not use the =:page= keyword before the weight value, the
page weight *must* be specified as the very first weight, even when
you specify the weights separately on each line.
***** Taxonomy weights and page weight (auto) 2
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: :tags auto
:EXPORT_HUGO_WEIGHT+: :page auto
:EXPORT_HUGO_WEIGHT+: :categories auto
:EXPORT_FILE_NAME: taxonomy-and-page-weights-auto-2
:END:
The page weight does not have to be specified as the very first weight
if using the =:page= keyword before the weight value.
* Dates                                                               :dates:
** Date                                                                :date:
*** Just date
:PROPERTIES:
:EXPORT_FILE_NAME: date-just-date
:EXPORT_DATE: 2017-09-12
:END:
The =date= for this post is Hugo-compatible i.e. [[https://tools.ietf.org/html/rfc3339#section-5.8][RFC3339-compliant]].
*** Date set using Org time stamp
:PROPERTIES:
:EXPORT_FILE_NAME: date-org-time-stamp
:EXPORT_DATE: <2018-01-23 Tue>
:END:
The =date= for this post is set in Org using the ~C-c . RET~ binding.
*** Date + Time
:PROPERTIES:
:EXPORT_FILE_NAME: date-plus-time
:EXPORT_DATE: 2017-09-12T16:10:00
:END:
*** Date + Time (UTC)
:PROPERTIES:
:EXPORT_FILE_NAME: date-plus-time-utc
:EXPORT_DATE: 2017-09-12T16:10:00Z
:END:
*** Date + Time (behind UTC)
:PROPERTIES:
:EXPORT_FILE_NAME: date-plus-time-minus-utc
:EXPORT_DATE: 2017-09-12T16:10:00-04:00
:END:
*** Date + Time (after UTC)
:PROPERTIES:
:EXPORT_FILE_NAME: date-plus-time-plus-utc
:EXPORT_DATE: 2017-09-12T16:10:00+05:30
:END:
*** DONE Parsing date from CLOSED property                           :closed:
CLOSED: [2018-01-23 Tue 14:10]
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-date-from-closed-property
:END:
When an Org TODO item is switched to the =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 :: [[https://orgmode.org/manual/Special-properties.html][(org) Special properties]] or =C-h i g (org) Special properties=
*** DONE Parsing date for a post which begins with a subheading      :closed:
CLOSED: [2017-09-11 Mon 14:32]
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-date-for-a-post-which-begins-with-a-subheading
:END:
**** The "CLOSED" state of this heading (which is nil) should be ignored
This is a test for {{{oxhugoissue(87)}}}.
*** Invalid Date                                                    :invalid:
:PROPERTIES:
:EXPORT_FILE_NAME: invalid-date
:EXPORT_DATE: 2012-2017
:END:
It's possible that someone is using an existing Org file to export to
Hugo. Some exporters like =ox-texinfo= recognize dates of style
=YEAR1-YEAR2= to use them in Copyright headers.

But that date is invalid as per the standard date format used by Hugo
in =date= front-matter, and also as per =org-parse-time-string=.

So in that case, don't allow =org-parse-time-string= to throw an error
and abort the export, but instead simply don't set the =date= in the
front-matter.

In this post the =:EXPORT_DATE:= property is set to =2012-2017=, but
the export will still happen fine, with the =date= front-matter not
set.
*** DONE Parsing date from LOGBOOK                         :logbook:noexport:
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-date-from-logbook
:LOG_INTO_DRAWER: t
:LOGGING: DONE(!)
:EXPORT_OPTIONS: d:t
:END:
:LOGBOOK:
- State "DONE"       from "DRAFT"      [2018-09-06 Thu 11:42]
- State "DONE"       from "DRAFT"      [2018-09-06 Thu 11:38]
:END:
#+begin_description
Parse the date from an entry like ~"- State "DONE" from "DRAFT"
[2018-09-06 Thu 11:25]~.
#+end_description
{{{oxhugoissue(203)}}}

In the case of multiple ~"State "DONE" from .."~ entries, use the
oldest entry to set the ~date~.
** Lastmod Date                                                     :lastmod:
*** Lastmod date set using Org time stamp
:PROPERTIES:
:EXPORT_FILE_NAME: lastmod-date-org-time-stamp
:EXPORT_HUGO_LASTMOD: <2018-01-23 Tue>
:END:
The =lastmod= for this post is set in Org using the ~C-c . RET~
binding.
*** Lastmod date set using Hugo-compatible date string
:PROPERTIES:
:EXPORT_FILE_NAME: lastmod-date-hugo-compatible-date
:EXPORT_HUGO_LASTMOD: 2018-01-23
:END:
The =lastmod= for this post is Hugo-compatible i.e. [[https://tools.ietf.org/html/rfc3339#section-5.8][RFC3339-compliant]].
*** DONE Parsing lastmod from LOGBOOK                      :logbook:noexport:
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-lastmod-from-logbook
:LOG_INTO_DRAWER: t
:LOGGING: DONE(!)
:EXPORT_OPTIONS: d:t
:END:
:LOGBOOK:
- State "DONE"       from "DRAFT"      [2018-09-06 Thu 11:41]
- State "DONE"       from "DRAFT"      [2018-09-06 Thu 11:40]
:END:
#+begin_description
If LOGBOOK has multiple entries of ~"- State "DONE" from .."~, use the
newest entry to parse the ~lastmod~ date from.
#+end_description
{{{oxhugoissue(203)}}}

In the case of multiple ~"State "DONE" from .."~ entries,
- Use the newest entry to set the ~lastmod~.
- Use the oldest entry to set the ~date~.

*Do not auto-set ~lastmod~ using ~current-time~ in this case.~
** Publish Date                                                 :publishdate:
*** Publish date set using Org time stamp
:PROPERTIES:
:EXPORT_FILE_NAME: publish-date-org-time-stamp
:EXPORT_HUGO_PUBLISHDATE: <2018-01-23 Tue>
:END:
The =publishdate= for this post is set in Org using the ~C-c . RET~
binding.
*** Publish date set using Hugo-compatible date string
:PROPERTIES:
:EXPORT_FILE_NAME: publish-date-hugo-compatible-date
:EXPORT_HUGO_PUBLISHDATE: 2018-01-23
:END:
The =publishdate= for this post is Hugo-compatible
i.e. [[https://tools.ietf.org/html/rfc3339#section-5.8][RFC3339-compliant]].
*** Publish date set using SCHEDULED                              :scheduled:
SCHEDULED: <2018-01-26 Fri>
:PROPERTIES:
:EXPORT_FILE_NAME: publish-date-scheduled
:END:
If a subtree has the =SCHEDULED= [[https://orgmode.org/manual/Special-properties.html][Special Property]] set, set the
=publishdate= front-matter to the scheduled date.

By default, =C-c C-s= in Org adds the =SCHEDULED= property to the
current subtree.
** Expiry Date                                                   :expirydate:
*** Expiry date set using Org time stamp
:PROPERTIES:
:EXPORT_FILE_NAME: expiry-date-org-time-stamp
:EXPORT_HUGO_EXPIRYDATE: <2999-01-23 Tue>
:END:
The =expirydate= for this post is set in Org using the ~C-c . RET~
binding.
*** Expiry date set using Hugo-compatible date string
:PROPERTIES:
:EXPORT_FILE_NAME: expiry-date-hugo-compatible-date
:EXPORT_HUGO_EXPIRYDATE: 2999-01-23
:END:
The =expirydate= for this post is Hugo-compatible
i.e. [[https://tools.ietf.org/html/rfc3339#section-5.8][RFC3339-compliant]].
*** Expiry date set using DEADLINE                                 :deadline:
DEADLINE: <2999-01-01 Tue>
:PROPERTIES:
:EXPORT_FILE_NAME: expiry-date-deadline
:END:
If a subtree has the =DEADLINE= [[https://orgmode.org/manual/Special-properties.html][Special Property]] set, set the
=expirydate= front-matter to the deadline date.

By default, =C-c C-d= in Org adds the =DEADLINE= property to the
current subtree.
** Customizing date format                                      :date_format:
*** Date with time and time-zone (default)                   :time_zone:time:
:PROPERTIES:
:EXPORT_FILE_NAME: date-with-time-and-time-zone
:EXPORT_DATE: <2018-01-29 Mon>
:END:
*** Date with time                                                     :time:
:PROPERTIES:
:EXPORT_FILE_NAME: date-with-time
:EXPORT_DATE: <2018-01-29 Mon>
:EXPORT_HUGO_DATE_FORMAT: %Y-%m-%dT%T
:END:
*** Date with only date                                           :only_date:
:PROPERTIES:
:EXPORT_FILE_NAME: date-with-only-date
:EXPORT_DATE: <2018-01-29 Mon>
:EXPORT_HUGO_DATE_FORMAT: %Y-%m-%d
:END:
* Preserve filling option                                           :filling:
** Filling is preserved
:PROPERTIES:
:EXPORT_FILE_NAME: filling-is-preserved
:EXPORT_HUGO_PRESERVE_FILLING: t
:END:
abc
def
ghi

{{{oxhugoissue(300)}}} --
Тест
Тест
** Filling is not preserved
:PROPERTIES:
:EXPORT_FILE_NAME: filling-is-not-preserved
:EXPORT_HUGO_PRESERVE_FILLING:
:END:
abc
def
ghi
** Chinese locale                                            :chinese:locale:
:PROPERTIES:
:EXPORT_HUGO_LOCALE: zh_CH
:END:
*** Filling automatically not preserved for Chinese characters (preserve filling on)
:PROPERTIES:
:EXPORT_FILE_NAME: filling-not-preserved-for-chinese-characters--preserve-filling-on
:EXPORT_HUGO_PRESERVE_FILLING: t
:END:
#+begin_description
Ensure that multi-byte characters are force-unwrapped if the locale is
manually set or auto-detected as Chinese.
#+end_description
abc
def
ghi
这是一个测试
文本

[[https://emacs-china.org/t/ox-hugo-auto-fill-mode-markdown/9547/5][Reference]]
*** Filling automatically not preserved for Chinese characters (preserve filling off)
:PROPERTIES:
:EXPORT_FILE_NAME: filling-not-preserved-for-chinese-characters--preserve-filling-off
:EXPORT_HUGO_PRESERVE_FILLING:
:END:
#+begin_description
Ensure that even when auto-unwrapping is enabled, no space is kept
between the unwrapped multi-byte characters if the locale is manually
set or auto-detected as Chinese.
#+end_description
abc
def
ghi
这是一个测试
文本

[[https://emacs-china.org/t/ox-hugo-auto-fill-mode-markdown/9547/5][Reference]]
* Section Inheritance                                   :section_inheritance:
** Section A
:PROPERTIES:
:EXPORT_HUGO_SECTION: section-a
:END:
*** Post A1
:PROPERTIES:
:EXPORT_FILE_NAME: post-a1
:END:
This post should be created in =content/section-a/=.
*** Category X                                                       :@cat_x:
**** Post AX
:PROPERTIES:
:EXPORT_FILE_NAME: post-ax
:END:
This post should also be created in =content/section-a/=.
* Keywords                                                          :keyword:
** TOC                                                                  :toc:
*** Post with TOC using keyword set to 0
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-toc-keyword-0
:END:
#+toc: headlines 0
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
*** Post with TOC using keyword set to 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-toc-keyword-2
:END:
#+toc: headlines 2
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
*** Post with TOC using keyword set to 6
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-toc-keyword-6
:END:
#+toc: headlines 6
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
*** TOC Local                                                         :local:
:PROPERTIES:
:EXPORT_FILE_NAME: toc-local
:END:
#+begin_description
Test the ~#+toc: headlines N local~ syntax where a TOC is exported
containing headlines only up to level-N relative to the headline in
which that keyword is used.
#+end_description
Below, TOC is exported with only level-1 headings in this post.
#+toc: headlines 1

Below exported TOC should look the same as above even when it's
generated using the ~local~ param as it is at the root level of this
post.
#+toc: headlines 1 local
**** Post sub-heading 1
Below, TOC is exported with only level-1 headings *relative to* this
"Post sub-heading 1" section.
#+toc: headlines 1 local
***** Post sub-heading 1.1
****** Post sub-heading 1.1.1
***** Post sub-heading 1.2
***** Post sub-heading 1.3
**** Post sub-heading 2
***** Post sub-heading 2.1
***** Post sub-heading 2.2
Below, TOC is exported with only up to level-2 headings *relative to*
this "Post sub-heading 2.2" section.
#+toc: headlines 2 local
****** Post sub-heading 2.2.1
****** Post sub-heading 2.2.2
****** Post sub-heading 2.2.3
Below, TOC is exported with only level-1 headings *relative to* this
"Post sub-heading 2.2.3" section.
#+toc: headlines 1 local
******* Post sub-heading 2.2.3.1
******* Post sub-heading 2.2.3.2
**** Post sub-heading 3
***** Post sub-heading 3.1
*** TOC :target                                                      :target:
:PROPERTIES:
:EXPORT_FILE_NAME: toc-target
:END:
#+begin_description
Test the ~#+toc~ keyword with ~:target~ attribute
#+end_description
{{{oxhugoissue(393)}}}
**** Reading
:PROPERTIES:
:EXPORT_OPTIONS: toc:3 num:3
:CUSTOM_ID: reading-material
:END:
***** landing page
#+toc: headlines 3 :target #reading-material
***** first subsection in Reading
**** Example from Org Manual
[[https://orgmode.org/manual/Table-of-Contents.html][Reference]]
***** Target
:PROPERTIES:
:CUSTOM_ID: TargetSection
:END:
****** Heading A
****** Heading B
***** Another section
#+toc: headlines 1 :target #TargetSection
* Pandoc Citations                                         :pandoc:citations:
:PROPERTIES:
:EXPORT_HUGO_PANDOC_CITATIONS: t
:EXPORT_BIBLIOGRAPHY: cite/bib/bib1.bib, cite/bib/bib2.bib
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :nocite '(@giovanelli2016 @eilan2016)
:EXPORT_HUGO_PAIRED_SHORTCODES: %mdshortcode myshortcode
:END:
** Citations Example (TOML)                                            :toml:
:PROPERTIES:
:EXPORT_FILE_NAME: citations-example-toml
:END:
#+begin_description
Test the parsing of Pandoc Citations, while also testing that ox-hugo
exported Markdown doesn't get broken -- TOML front-matter.
#+end_description
{{{oxhugoissue(175)}}}
*** Section 1
Here is a test example file with an in-text citation where someone
important says something important (e.g. @loncar2016). And here is
another bit of blah with a footnote citation.[fn:5]

See [[#citation-example-toml-section-2]].
*** Section 2
:PROPERTIES:
:CUSTOM_ID: citation-example-toml-section-2
:END:
Content in section 2.
*** Testing random Hugo shortcode
#+begin_mdshortcode
Text containing *Markdown*
#+end_mdshortcode
Some text.
#+begin_myshortcode
Text not containing *Markdown*
#+end_myshortcode
*** Testing ox-hugo inserted HTML div tags
#+begin_foo
*bold* /italics/
#+end_foo
*** Testing tables
|----------+----------+----------|
| Header 1 | Header 2 | Header 3 |
|----------+----------+----------|
| a        | b        | c        |
| d        | e        | f        |
|----------+----------+----------|
*** Testing fenced code blocks
#+begin_src emacs-lisp
(message "Hello World")
#+end_src
*** Lists Galore
- item1 in list
- item2 in list. The following list is in a separate list body.


- L1 -- foo1
- L1 -- foo2
  - L2 -- bar1
  - L2 -- bar2
    + L3 -- baz1
    + L3 -- baz2
      - L4 -- zoo1
      - L4 -- zoo2
        1. L5 -- numbered1
        2. L5 -- numbered2
      - L4 -- zoo1
      - L4 -- zoo2
    + L3 -- baz1
    + L3 -- baz2
  - L2 -- bar1
  - L2 -- bar2
- L1 -- foo1
- L1 -- foo2
** Citations Example (YAML)                                            :yaml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:EXPORT_FILE_NAME: citations-example-yaml
:END:
#+begin_description
Test the parsing of Pandoc Citations, while also testing that ox-hugo
exported Markdown doesn't get broken -- YAML front-matter.
#+end_description
{{{oxhugoissue(175)}}}
*** Section 1
Here is a test example file with an in-text citation where someone
important says something important (e.g. @loncar2016). And here is
another bit of blah with a footnote citation.[fn:5]

See [[#citation-example-yaml-section-2]].
*** Section 2
:PROPERTIES:
:CUSTOM_ID: citation-example-yaml-section-2
:END:
Content in section 2.
** Citation Linking                                          :link_citations:
:PROPERTIES:
:EXPORT_FILE_NAME: citation-linking
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :link-citations true
:END:
#+begin_description
Auto-link citations from post body to the citation in References
section.
#+end_description
Here is a test example file with an in-text citation where someone
important says something important (e.g. @loncar2016). And here is
another bit of blah with a footnote citation.[fn:5]
** Citation Forms                                                     :forms:
:PROPERTIES:
:EXPORT_BIBLIOGRAPHY: cite/bib/bib3.bib
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :link-citations true
:END:
*** Citation Forms Test Body
:PROPERTIES:
:CUSTOM_ID: citation-forms-test-body
:END:
**** Citations in square brackets
The citations withing square brackets will be rendered within
parentheses.
#+begin_src org
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].
#+end_src
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

#+begin_src org
Blah blah [@doe99, pp. 33-35, 38-39].
#+end_src
Blah blah [@doe99, pp. 33-35, 38-39].

#+begin_src org
Blah blah [@smith04; @doe99].
#+end_src
Blah blah [@smith04; @doe99].
**** Citations with author name suppressed
A minus sign (~-~) before the ~@~ will suppress mention of the author
in the citation. This can be useful when the author is already
mentioned in the text.
#+begin_src org
Smith says blah [-@smith04].
#+end_src
Smith says blah [-@smith04].
**** In-text citations (no square brackets)
#+begin_src org
@smith04 says blah.
#+end_src
@smith04 says blah.

#+begin_src org
@smith04 [p. 33] says blah.
#+end_src
@smith04 [p. 33] says blah.
**** Actual citations for this test post :)
See @addCite17; @rmdCitations for more.
*** Citation Forms
:PROPERTIES:
:EXPORT_FILE_NAME: citation-forms
:END:
#+begin_description
Demonstrating different styles / forms of citations
#+end_description
#+include: "./all-posts.org::#citation-forms-test-body" :only-contents t
*** Citation Forms (Custom CSL)                                   :forms:csl:
:PROPERTIES:
:EXPORT_FILE_NAME: citation-forms-apa-csl
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :csl cite/csl/apa.csl
:END:
#+begin_description
Demonstrating different styles / forms of citations using APA CSL
#+end_description
#+include: "./all-posts.org::#citation-forms-test-body" :only-contents t

*Compare the References section below with [[/posts/citation-forms/#references][that]] when using the default
 CSL.*
** No Citations                                                        :none:
:PROPERTIES:
:EXPORT_FILE_NAME: citations-none
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :nocite '()
:END:
This post has Pandoc Citations parsing enabled, but has no actual
citations.
** Invalid Nocites                                           :invalid:nocite:
:PROPERTIES:
:EXPORT_FILE_NAME: invalid-nocites
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :nocite '(@foo @bar)
:END:
This post has citations ~@foo~ and ~@bar~ listed in ~nocite~
meta-data. But they are invalid as they don't exist in any of the
bibliography files.

But that generates neither a Pandoc warning nor error.

As the final Pandoc output Markdown ends up with *no* references, the
Pandoc output is discarded, and the original ~ox-hugo~ output is used
instead.
** Citations with captions                          :caption:figure:plantuml:
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: citations-with-captions
:EXPORT_FILE_NAME: index
:EXPORT_DATE: 2018-08-19
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :link-citations true
:END:
#+begin_description
This test tests the following:
- Pandoc leave the HTML ~span~ tags as-is.
- Pandoc does not escape the ~<~ in the ~figure~ shortcodes with
  captions (in general: ~{{< ..>}}~ shortcodes that could wrap across
  lines).
- While Pandoc auto-wraps the re-written Markdown, it also wraps the
  ~{{< .. >}}~ shortcodes. The test checks that such "wrapped
  shortcodes" get unwrapped.
#+end_description
{{{oxhugoissue(191)}}}

#+name: code__plantuml_nested_boxes
#+caption: Nested Boxes using PlantUML
#+begin_src plantuml :file images/citations-with-captions/nested-boxes.svg :eval yes :exports both
rectangle "<html>, <body>, etc." as a  {
  rectangle "<div>..." as b #antiquewhite {
    rectangle "<video>...\n\n\n" as c
  }
}
#+end_src
# The order of #+caption and #+RESULTS is important here.
# Ref: https://emacs.stackexchange.com/a/12155/115
#+caption: PlantUML generated figure showing nested boxes
#+RESULTS: code__plantuml_nested_boxes
[[file:images/citations-with-captions/nested-boxes.svg]]
** Disabling Pandoc citations in a subtree                          :disable:
*** Disabling Pandoc citations in a subtree (empty string)
:PROPERTIES:
:EXPORT_FILE_NAME: disabling-pandoc-citations-in-a-subtree-empty-string
:EXPORT_HUGO_PANDOC_CITATIONS:
:END:
#+begin_description
Test that ~:EXPORT_HUGO_PANDOC_CITATIONS:~ disables Pandoc citations
in a subtree.
#+end_description
The Nocites in the front-matter do not get rendered as citations.
*** Disabling Pandoc citations in a subtree (nil string)
:PROPERTIES:
:EXPORT_FILE_NAME: disabling-pandoc-citations-in-a-subtree-nil-string
:EXPORT_HUGO_PANDOC_CITATIONS: nil
:END:
#+begin_description
Test that ~:EXPORT_HUGO_PANDOC_CITATIONS: nil~ disables Pandoc
citations in a subtree.
#+end_description
The Nocites in the front-matter do not get rendered as citations.
* Export Options                                              :export_option:
** Table of Contents (TOC)                                              :toc:
=ox-hugo= has the =with-toc= option disabled by default as Hugo has an
inbuilt TOC generation feature.

Still some people might prefer to use the Org generated TOC.
*** Section Numbers                                                     :num:
**** Don't number headlines or TOC
:PROPERTIES:
:EXPORT_FILE_NAME: options-num-nil
:EXPORT_OPTIONS: num:nil
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
**** Don't number headlines (but yes in TOC)
:PROPERTIES:
:EXPORT_FILE_NAME: options-num-onlytoc
:EXPORT_OPTIONS: num:onlytoc
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
**** Number 0 levels
:PROPERTIES:
:EXPORT_FILE_NAME: options-num-0
:EXPORT_OPTIONS: num:0
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
**** Number 2 levels
:PROPERTIES:
:EXPORT_FILE_NAME: options-num-2
:EXPORT_OPTIONS: num:2
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
**** Number all levels
:PROPERTIES:
:EXPORT_FILE_NAME: options-num-all
:EXPORT_OPTIONS: num:t
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
*** TOC
**** =num= set to =nil=
***** TOC with all headings (unnumbered)
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-t-num-nil
:EXPORT_OPTIONS: num:nil toc:t
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
***** TOC with headings (unnumbered) only till level 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-2-num-nil
:EXPORT_OPTIONS: num:nil toc:2
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
***** No TOC as toc set to nil
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-nil-num-nil
:EXPORT_OPTIONS: num:nil toc:nil
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
**** =num= set to =t=
***** TOC with all headings (numbered, except for selected unnumbered)
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-t-num-t
:EXPORT_OPTIONS: num:t toc:t
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
***** TOC with headings (numbered, except for selected unnumbered) only till level 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-2-num-t
:EXPORT_OPTIONS: num:t toc:2
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
***** No TOC as toc set to 0
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-0-num-t
:EXPORT_OPTIONS: num:t toc:0
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
**** =num= set to =onlytoc=
***** TOC with all headings (post-unnumbered, TOC-numbered)
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-t-num-onlytoc
:EXPORT_OPTIONS: num:onlytoc toc:t
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
***** TOC with headings (post-unnumbered, TOC-numbered) only till level 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-export-options-toc-1-num-onlytoc
:EXPORT_OPTIONS: num:onlytoc toc:1
:END:
#+include: "./all-posts.org::#nested-sections-example" :only-contents t
**** No TOC in Summary                                       :summary:endtoc:
***** No TOC in Summary (with more comment marker)                     :more:
:PROPERTIES:
:EXPORT_FILE_NAME: no-toc-in-summary--with-more
:EXPORT_OPTIONS: toc:t
:END:
By default, Hugo will dump everything at the beginning of a post into
its =.Summary= (See [[https://gohugo.io/content-management/summaries/][Hugo content summaries]]). As TOC enabled using the
export option like =toc:t= is inserted at the beginning of a post, TOC
will be shown in that summary too!

In this example, the special comment =more= *is used*.

#+hugo: more

****** =ox-hugo='s Solution
=ox-hugo= helps prevent that with a workaround.. it inserts a special
HTML comment *=<!--endtoc-->=* after the TOC.
****** Snippet
As the =more= comment is present, the [[https://github.com/kaushalmodi/hugo-bare-min-theme/blob/master/layouts/partials/summary_minus_toc.html][=summary_minus_toc.html=]] partial
used for this test site ensures that only the content between
~<!--endtoc-->~ and ~<!--more-->~ is considered as summary.

This partial needs to be used wherever the summary text is needed
(example: the Opengraph =og:description= meta tag).
***** No TOC in Summary (without more comment marker)
:PROPERTIES:
:EXPORT_FILE_NAME: no-toc-in-summary--without-more
:EXPORT_OPTIONS: toc:t
:END:
By default, Hugo will dump everything at the beginning of a post into
its =.Summary= (See [[https://gohugo.io/content-management/summaries/][Hugo content summaries]]). As TOC enabled using the
export option like =toc:t= is inserted at the beginning of a post, TOC
will be shown in that summary too!

In this example, the special comment =more= is *not* used.

****** =ox-hugo='s Solution
=ox-hugo= helps prevent that with a workaround.. it inserts a special
HTML comment *=<!--endtoc-->=* after the TOC.
****** Snippet
As the =more= comment is not present, the [[https://github.com/kaushalmodi/hugo-bare-min-theme/blob/master/layouts/partials/summary_minus_toc.html][=summary_minus_toc.html=]]
partial used for this test site ensures that only the first 300 (or
so) characters after ~<!--endtoc-->~ is considered as summary.

This partial needs to be used wherever the summary text is needed
(example: the Opengraph =og:description= meta tag).
**** TOC with TODO headlines                                           :todo:
***** CSS for TODO                                                 :noexport:
:PROPERTIES:
:CUSTOM_ID: todo-css
:END:
#+begin_export html
<style>
.org-todo {
    font-size: 0.8em;
    font-weight: 700;
}
/* *** Org TODO set to TODO state */
.org-todo.todo {
    color: #e60000;
}
/* *** Org TODO set to DONE state */
.org-todo.done {
    color: green;
}
</style>
#+end_export
***** TOC with TODO enabled (default)                                :enable:
:PROPERTIES:
:EXPORT_FILE_NAME: toc-with-todo-enabled
:EXPORT_OPTIONS: toc:t todo:t
:END:
#+begin_description
TODO states if present are prefixed to the headings -- both in the body
and TOC.
#+end_description
#+include: "./all-posts.org::#todo-css" :only-contents t
****** No TODO state
****** TODO Something to do
****** DONE Something done
CLOSED: [2018-06-12 Tue 22:12]
***** TOC with TODO disabled                                        :disable:
:PROPERTIES:
:EXPORT_FILE_NAME: toc-with-todo-disabled
:EXPORT_OPTIONS: toc:t todo:nil
:END:
#+begin_description
No TODO states are prefixed to the headings -- neither in the body, nor
in the TOC.
#+end_description
#+include: "./all-posts.org::#todo-css" :only-contents t
****** No TODO state
****** TODO Something to do
****** DONE Something done
CLOSED: [2018-06-12 Tue 22:12]
** Sub/superscripts                                 :superscripts:subscripts:
*** Sub/superscripts require braces
:PROPERTIES:
:EXPORT_FILE_NAME: sub-superscripts-require-braces
:END:
By default, =ox-hugo= implements the =^:{}= export option. See =C-h v
org-export-with-sub-superscripts= for details. With this option, the
text that needs to be subscripted or superscripted has to be
surrounded by braces ={..}= following the =_= or =^=.
**** Following text will export =_= and =^= verbatim
a_b a_bc a^b a^bc
**** Following text will export =_{..}= as subscript and =^{..}= as superscript
a_{b} a_{bc} a^{b} a^{bc}
*** Sub/superscripts don't require braces
:PROPERTIES:
:EXPORT_FILE_NAME: sub-superscripts-dont-require-braces
:EXPORT_OPTIONS: ^:t
:END:
**** Following text will export =_..= as subscript and =^..= as superscript
a_b a_bc a^b a^bc
**** Following text will export =_{..}= as subscript and =^{..}= as superscript
a_{b} a_{bc} a^{b} a^{bc}
** Disable exporting title                                    :title:disable:
:PROPERTIES:
:EXPORT_OPTIONS: title:nil
:EXPORT_FILE_NAME: disable-title-2
:END:
This post will be exported without =title= in the front-matter because
it is disabled using =:EXPORT_OPTIONS: title:nil=.
** Disable exporting author                                  :author:disable:
:PROPERTIES:
:EXPORT_OPTIONS: author:nil
:EXPORT_FILE_NAME: disable-author
:EXPORT_AUTHOR: Foo Bar
:END:
This post will be exported without =author= in the front-matter because
it is disabled using =:EXPORT_OPTIONS: author:nil=.
** Creator                                             :creator:front_matter:
*** Default Creator
:PROPERTIES:
:EXPORT_DATE: 2017-12-01
:EXPORT_OPTIONS: creator:t
:EXPORT_FILE_NAME: default-creator
:END:
The front-matter for this post contains the default Creator string.
*** Custom Creator
:PROPERTIES:
:EXPORT_CREATOR: The awesome Emacs + Org-mode + ox-hugo + Hugo
:EXPORT_OPTIONS: creator:t
:EXPORT_FILE_NAME: custom-creator
:END:
The front-matter for this post contains a custom Creator string.
* Export snippets and blocks
** Export snippet                                            :export_snippet:
*** Export snippet Hugo                                                :hugo:
:PROPERTIES:
:EXPORT_FILE_NAME: export_snippet_hugo
:END:
@@hugo:This will get exported **only for** Hugo exports, `verbatim`.@@

@@hugo:Newlines in Org source
between the `@​@` pairs are
allowed too
(but no blank lines).@@

Use *Export Blocks* if you need blank lines in-between.
*** Export snippet Markdown                                        :markdown:
:PROPERTIES:
:EXPORT_FILE_NAME: export_snippet_markdown
:END:
@@md:This Markdown **Export Snippet** will also get exported for Hugo
exports, `verbatim`.@@

@@markdown:_This one too_@@
- NOTE :: =ox-md.el= does not support *Export Snippets* as of writing
          this <2017-12-08 Fri>. So even the =@@md:foo@@= and
          =@@markdown:foo@@= snippets are handled by =ox-hugo=
          directly.
*** Export snippet HTML                                                :html:
:PROPERTIES:
:EXPORT_FILE_NAME: export_snippet_html
:END:
@@html:This HTML <b>Export Snippet</b> will also get exported for Hugo
exports, <code>verbatim</code>.@@
** Export block                                                :export_block:
*** Export block Hugo                                                  :hugo:
:PROPERTIES:
:EXPORT_FILE_NAME: export_block_hugo
:END:
#+begin_export hugo
This will get exported **only for** Hugo exports, `verbatim`.
#+end_export
*** Export block Markdown                                          :markdown:
:PROPERTIES:
:EXPORT_FILE_NAME: export_block_markdown
:END:
#+begin_export markdown
This Markdown **Export Block** will also get exported for Hugo exports,
`verbatim` ..
#+end_export

#+begin_export md
and **this too**.
#+end_export
*** Export block HTML                                                  :html:
:PROPERTIES:
:EXPORT_FILE_NAME: export_block_html
:END:
#+begin_export html
This HTML <b>Export Block</b>  will also get exported for Hugo exports,
<code>verbatim</code>.

And Markdown emphasis characters like *, `  and _ will not escaped in here.
#+end_export

From {{{oxhugoissue(154)}}}, we see an actual case of where that =*=
will need to remain unescaped:

#+begin_src org
# Org source
,#+begin_export html
<div>
  <script type="text/javascript">
    var a = 3;
    var b = 2*a;
  </script>
</div>
,#+end_export
#+end_src

#+begin_export html
<div>
  <script type="text/javascript">
    var a = 3;
    var b = 2*a;
  </script>
</div>
#+end_export
**** ~#+begin_export html~ blocks with script tag
{{{oxhugoissue(369)}}}

Check that ~src="https://example.com"~ does not become
~src="<https://example.com>"~.

- Note :: Below iframe/script will *not* work on this site because of
          the strict [[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP][CSP]]. Anyways. this site is to test just the
          Markdown exported by ox-hugo. So please see "/✱ Markdown
          source of this page/" above.

#+begin_src org
,#+begin_export html
<div class="glitch-embed-wrap" style="height: 420px; width: 100%;">
  <iframe
    src="https://glitch.com/embed/#!/embed/silken-football?path=app.py&previewSize=0&sidebarCollapsed=true"
    title="silken-football on Glitch"
    style="height: 100%; width: 100%; border: 0;">
  </iframe>
</div>
,#+end_export
#+end_src

#+begin_export html
<div class="glitch-embed-wrap" style="height: 420px; width: 100%;">
  <iframe
    src="https://glitch.com/embed/#!/embed/silken-football?path=app.py&previewSize=0&sidebarCollapsed=true"
    title="silken-football on Glitch"
    style="height: 100%; width: 100%; border: 0;">
  </iframe>
</div>
#+end_export
**** To see the exported HTML
/See the Markdown source of this page to see the verbatim-inserted
HTML./
* Miscellaneous Front Matter                                   :front_matter:
** Hugo Aliases                                                     :aliases:
*** Alias without section portion 1
:PROPERTIES:
:EXPORT_FILE_NAME: alias-without-section-1
:EXPORT_HUGO_ALIASES: alias-a
:END:
As the specified alias does not contain the "/" string, it will be
auto-prefixed with the section for the current post.
*** New section just for test
:PROPERTIES:
:EXPORT_HUGO_SECTION: alias-test
:END:
**** Alias without section portion 2
:PROPERTIES:
:EXPORT_FILE_NAME: alias-without-section-2
:EXPORT_HUGO_ALIASES: alias-b
:END:
As the specified alias does not contain the "/" string, it will be
auto-prefixed with the section for the current post.
*** Alias specifying a different section
:PROPERTIES:
:EXPORT_FILE_NAME: alias-different-section
:EXPORT_HUGO_ALIASES: /alias-test/alias-c
:END:
*** Alias specifying root section
:PROPERTIES:
:EXPORT_FILE_NAME: alias-root-section
:EXPORT_HUGO_ALIASES: /alias-d
:END:
*** Multiple aliases without section portion
:PROPERTIES:
:EXPORT_FILE_NAME: alias-multiple-without-section
:EXPORT_HUGO_ALIASES: alias-e alias-f
:END:
*** Multiple aliases with section portion
:PROPERTIES:
:EXPORT_FILE_NAME: alias-multiple-with-section
:EXPORT_HUGO_ALIASES: /alias-test/alias-g /alias-test/alias-h
:END:
** Author                                                            :author:
*** Single author parent subtree
:PROPERTIES:
:EXPORT_AUTHOR: Foo Bar
:END:
**** Single author
:PROPERTIES:
:EXPORT_FILE_NAME: single-author
:END:
This post has 1 author set as a TOML list in front-matter.
*** Single author as a custom parameter                           :custom_fm:
:PROPERTIES:
:EXPORT_FILE_NAME: single-author-custom
:EXPORT_AUTHOR:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :author "Foo Bar"
:END:
This post has 1 author set as a TOML string in front-matter.
*** Multiple authors
:PROPERTIES:
:EXPORT_FILE_NAME: multiple-authors
:EXPORT_AUTHOR: Foo Bar, Toto Kumar  , Zulu ,Ágota Kristóf
:END:
This post has multiple authors. In Org, multiple authors are added
comma-separated.
*** Uniquify duplicate authors                                    :duplicate:
:PROPERTIES:
:EXPORT_FILE_NAME: duplicate-authors
:EXPORT_AUTHOR: Foo Bar, Foo Bar
:END:
#+begin_description
Test that duplicate authors get uniquified in the export.
#+end_description
The duplication can happen in real use if an Org setup file has the
same author as in the Org document where that file is included using
~SETUPFILE~. This test mimics this case:
#+begin_src org
,#+setupfile: some-file.org # some-file.org contains "#+author: Foo Bar"
,#+author: Foo Bar
#+end_src
** Keywords                                                        :keywords:
*** Single keyword in front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: single-keyword-in-front-matter
:EXPORT_KEYWORDS: abc
:END:
*** Multiple keywords in front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: multiple-keywords-in-front-matter
:EXPORT_KEYWORDS: abc def hyphenated-keyword underscored_keyword "two words" "these are four words"
:END:
*** Keywords set using multiple properties
:PROPERTIES:
:EXPORT_FILE_NAME: keywords-set-using-multiple-properties
:EXPORT_KEYWORDS: abc
:EXPORT_KEYWORDS+: def
:END:
** Description                                                  :description:
*** Description meta-data with "quoted text"
:PROPERTIES:
:EXPORT_FILE_NAME: post-description-quotes
:EXPORT_DESCRIPTION: Some description with "quoted text"
:EXPORT_DATE: 2017-07-24
:END:
Testing a post with double quotes in the description.
*** Description set using Org Special Block                   :special_block:
**** TOML                                                              :toml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: toml
:END:
***** Single-line description set using Org Special Block (TOML) :single_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-single-line-org-special-block-toml
:END:
#+begin_description
Short description --- *bold* -- /italics/ --- +strikethrough+ =monospace=
#+end_description
Post content.
***** Multi-line description set using Org Special Block (TOML)  :multi_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-multi-line-org-special-block-toml
:END:
#+begin_description
Short description
of this post

*bold* -- /italics/ --- +strikethrough+ =monospace=

These lines \\
show up with line breaks \\
but within the same paragraph.
#+end_description
Post content.
***** Special block description overrides property-set description
:PROPERTIES:
:EXPORT_FILE_NAME: description-special-block-description
:EXPORT_DESCRIPTION: Description set in subtree property
:END:
If the description is set via the subtree property
=:EXPORT_DESCRIPTION= (or the =#+description= keyword), and via the
"description" special block too, the latter will take precedence.
#+begin_description
Description set in special block
#+end_description
***** Single-line description with backslashes (TOML) :escaping:backslashes:single_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-single-line-escaping-backslashes-org-special-block-toml
:END:
#+begin_description
Test to check that backslashes in =\|= and =\\= are correctly escaped.
#+end_description
Post content.
***** Multi-line description with backslashes (TOML) :escaping:backslashes:multi_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-multi-line-escaping-backslashes-org-special-block-toml
:END:
#+begin_description
Test to check that backslashes in =\|= and =\\= are correctly escaped
in the front-matter.
#+end_description
Post content.
**** YAML                                                              :yaml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
***** Single-line description set using Org Special Block (YAML) :single_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-single-line-org-special-block-yaml
:END:
#+begin_description
Short description --- *bold* -- /italics/ --- +strikethrough+ =monospace=
#+end_description
Post content.
***** Multi-line description set using Org Special Block (YAML)  :multi_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-multi-line-org-special-block-yaml
:END:
#+begin_description
Short description
of this post

*bold* -- /italics/ --- +strikethrough+ =monospace=

These lines \\
show up with line breaks \\
but within the same paragraph.
#+end_description
Post content.
***** Single-line description with backslashes (YAML) :escaping:backslashes:single_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-single-line-escaping-backslashes-org-special-block-yaml
:END:
#+begin_description
Test to check that backslashes in =\|= and =\\= are correctly escaped.
#+end_description
Post content.
***** Multi-line description with backslashes (YAML) :escaping:backslashes:multi_line:
:PROPERTIES:
:EXPORT_FILE_NAME: description-multi-line-escaping-backslashes-org-special-block-yaml
:END:
#+begin_description
Test to check that backslashes in =\|= and =\\= are correctly escaped
in the front-matter.
#+end_description
Post content.
** Locale                                                            :locale:
:PROPERTIES:
:EXPORT_HUGO_WITH_LOCALE: t
:END:
*** Specified locale in front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: locale-specified
:EXPORT_HUGO_LOCALE: es_ES
:END:
#+begin_description
Specify the locale using ~:EXPORT_HUGO_LOCALE: es_ES~ property.
#+end_description
Locale exporting is enabled using ~:EXPORT_HUGO_WITH_LOCALE: t~ in the
post's parent subtree.
*** Auto-detected locale in front-matter                        :auto_detect:
:PROPERTIES:
:EXPORT_FILE_NAME: locale-auto-detect
:END:
#+begin_description
Locale is not specified, so is auto-detected.
#+end_description
Locale exporting is enabled using ~:EXPORT_HUGO_WITH_LOCALE: t~ in the
post's parent subtree.
** Images                                                            :images:
*** Single image                                                     :single:
:PROPERTIES:
:EXPORT_FILE_NAME: images-single
:EXPORT_HUGO_IMAGES: "image path with space.png"
:END:
If an image path has spaces in it, wrap the whole path in double
quotes.
*** Multiple images                                                :multiple:
:PROPERTIES:
:EXPORT_FILE_NAME: images-multiple
:EXPORT_HUGO_IMAGES: "image foo.svg"
:EXPORT_HUGO_IMAGES+: images/bar.png
:EXPORT_HUGO_IMAGES+: zoo.jpg
:END:
If an image path has spaces in it, wrap the whole path in double
quotes.
** Videos                                                            :videos:
*** Single video                                                     :single:
:PROPERTIES:
:EXPORT_FILE_NAME: videos-single
:EXPORT_HUGO_VIDEOS: "video path with space.mp4"
:END:
If a video path has spaces in it, wrap the whole path in double
quotes.
*** Multiple videos                                                :multiple:
:PROPERTIES:
:EXPORT_FILE_NAME: videos-multiple
:EXPORT_HUGO_VIDEOS: "video foo.mp4"
:EXPORT_HUGO_VIDEOS+: bar.mpeg
:END:
If a video path has spaces in it, wrap the whole path in double
quotes.
** Audio                                                              :audio:
:PROPERTIES:
:EXPORT_FILE_NAME: audio-front-matter
:EXPORT_HUGO_AUDIO: "audio path with space.mp3"
:END:
If the audio path has spaces in it, wrap the whole path in double
quotes.
** Series                                                            :series:
*** Single series                                                    :single:
:PROPERTIES:
:EXPORT_FILE_NAME: series-single
:EXPORT_HUGO_SERIES: "Series A"
:END:
If a series name has spaces in it, wrap the whole name in double
quotes.
*** Multiple series                                                :multiple:
:PROPERTIES:
:EXPORT_FILE_NAME: series-multiple
:EXPORT_HUGO_SERIES: "Series A"
:EXPORT_HUGO_SERIES+: "Series B"
:END:
If a series name has spaces in it, wrap the whole name in double
quotes.
** Type                                                                :type:
*** Type Front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: type-front-matter
:EXPORT_HUGO_TYPE: type-test
:END:
The =type= front-matter is used to override the default *section* type
(automatically derived from the directory of the content page).

Here the type is overridden to be =type-test=.

[[https://gohugo.io/content-management/front-matter/#predefined][Reference]]
*** Type + Layout Front-matter                                       :layout:
:PROPERTIES:
:EXPORT_FILE_NAME: type-and-layout-front-matter
:EXPORT_HUGO_TYPE: type-test
:EXPORT_HUGO_LAYOUT: alternate-single
:END:
Here both =type= *and* =layout= are overridden.
** Layout Front-matter                                               :layout:
:PROPERTIES:
:EXPORT_FILE_NAME: layout-front-matter
:EXPORT_HUGO_LAYOUT: alternate-single
:END:
The =layout= front-matter is used to override the default *single*
layout of a regular page. See [[https://gohugo.io/templates/lookup-order/][Template Lookup Order]] to learn more.

Here the layout is overridden to be =alternate-single=.

[[https://gohugo.io/content-management/front-matter/#predefined][Reference]]
** URL Front-matter                                                     :url:
:PROPERTIES:
:EXPORT_FILE_NAME: url-front-matter
:EXPORT_HUGO_URL: foo/bar/zoo/url-front-matter
:END:
The =url= front-matter is used to specify *the full path to the
content from the web root*. It makes no assumptions about the path of
the content file. It also ignores any language prefixes of the
multilingual feature.

[[https://gohugo.io/content-management/front-matter/#predefined][Reference]]
** Linktitle Front-matter                                         :linktitle:
:PROPERTIES:
:EXPORT_FILE_NAME: linktitle-front-matter
:EXPORT_HUGO_LINKTITLE: My link title
:END:
The =linktitle= front-matter is used for creating links to content. If
set, Hugo defaults to using the =linktitle= before the =title=.
** Slug Front-matter                                                   :slug:
:PROPERTIES:
:EXPORT_FILE_NAME: slug-front-matter
:EXPORT_HUGO_SLUG: this-is-how-i-want-to-name-this-link
:END:
By default, a page's /slug/ is the name of the content file (sans
extension). So in this case, it would have been
=slug-front-matter=. But that slug is overridden using the specified
=slug= in the front-matter: =this-is-how-i-want-to-name-this-link=.
** Markup Front-matter                                               :markup:
:PROPERTIES:
:EXPORT_FILE_NAME: markup-front-matter
:EXPORT_HUGO_MARKUP: org
:END:
The markup for this post is set to =org=. So the Markdown markup based
emphasis *won't work* here.
** Replace front-matter keys                                   :keys:replace:
*** Replace "description" with "summary"                :description:summary:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-description-with-summary
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: description>summary
:END:
#+begin_description
This should be rendered as ~.Summary~ in Hugo v0.55+. For only Hugo
versions, this will front-matter can be retrieved only as
~.Params.summary~.
#+end_description
This text will be in the post body.
*** Replace only "linkTitle" key                                  :linktitle:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-only-linktitle-key
:EXPORT_HUGO_LINKTITLE: Replace only "linkTitle" key
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: linkTitle>linktitle
:END:
This post will have the =linkTitle= key in front-matter replaced with
=linktitle=.
*** Replace only "tags" key                                            :tags:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-only-tags-key
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: tags>keywords
:END:
This post will have the =tags= key in front-matter replaced with
=keywords=.
*** Replace only "categories" key                    :categories:@test_cat_x:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-only-categories-key
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: categories>cats
:END:
This post will have the =categories= key in front-matter replaced with
=cats=.
*** Replace both "tags" and "categories" keys   :tags:categories:@test_cat_x:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-both-tags-and-categories-keys
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: tags>keywords categories>cats
:END:
This post will have the =tags= key in front-matter replaced with
=keywords= and =categories= replaced with =cats=.
*** Replace keys using multiple properties      :@test_cat_x:tags:categories:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-keys-using-multiple-properties
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: tags>keywords
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE+: categories>cats
:END:
This post will have the =tags= key in front-matter replaced with
=keywords= and =categories= replaced with =cats=.
*** Swap tags and categories               :@test_cat_x:tags:categories:swap:
:PROPERTIES:
:EXPORT_FILE_NAME: swap-tags-and-categories
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: tags>categories categories>tags
:END:
This post will have the =tags= and =categories= keys in the
front-matter swapped.
*** Replace custom keys                                              :custom:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-custom-keys
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :foo 1 :bar 2
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: foo>myfoo bar>mybar
:END:
This post will have the =foo= key in front-matter replaced with
=myfoo= and =bar= replaced with =mybar=.
*** Attempt to replace non-existing keys                       :non_existing:
:PROPERTIES:
:EXPORT_FILE_NAME: replace-non-existing-keys
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: toto>zulu
:END:
Here, attempt is made to replace a non-existing key =toto=, but still,
there shouldn't be any error.
*** Make the author front-matter plural                              :author:
:PROPERTIES:
:EXPORT_FILE_NAME: plural-author-front-matter
:EXPORT_AUTHOR: Mark Twain, Arthur Conan Doyle
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: author>authors
:END:
Some themes might expect the front-matter list variable for authors to
be ~authors~ instead of the default ~author~ created by ~ox-hugo~.
*** Remove a front-matter key                                        :remove:
:PROPERTIES:
:EXPORT_FILE_NAME: remove-a-front-matter-key
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :foo 1 :bar 2
:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: foo>nil bar>zoo
:END:
#+begin_description
This test removes the ~foo~ front-matter key from the exported file
(and replaces ~bar~ key with ~zoo~).
#+end_description
** DONE Parsing notes from LOGBOOK                   :notes:logbook:noexport:
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-notes-from-logbook
:LOG_INTO_DRAWER: t
:LOGGING: TODO(!) DRAFT(!) DONE(!)
:EXPORT_OPTIONS: d:t
:END:
:LOGBOOK:
- Note taken on [2018-09-06 Thu 11:45] \\
  Another note.
- Note taken on [2018-09-06 Thu 11:37] \\
  A note
- State "DONE"       from "DRAFT"      [2018-09-06 Thu 11:25]
- State "DRAFT"      from "TODO"       [2018-09-06 Thu 11:25]
- State "TODO"       from              [2018-09-06 Thu 11:25]
:END:
#+begin_description
Parse notes from LOGBOOK into a TOML table (YAML map?) of ~notes~
front-matter.
#+end_description

{{{oxhugoissue(203)}}}

For example,

#+begin_src org
:LOGBOOK:
- Note taken on [2018-09-06 Thu 11:45] \\
  Another note.
- Note taken on [2018-09-06 Thu 11:37] \\
  A note
- State "DONE"       from "DRAFT"      [2018-09-06 Thu 11:25]
- State "DRAFT"      from "TODO"       [2018-09-06 Thu 11:25]
- State "TODO"       from              [2018-09-06 Thu 11:25]
:END:
#+end_src

should export these ~notes~ in TOML front-matter (and the equivalent
in YAML):
#+begin_src toml
[[notes]]
  index = 0
  date = 2018-09-06T11:37:00-04:00
  content = "A note."
[[notes]]
  index = 1
  date = 2018-09-06T11:45:00-04:00
  content = "Another note."
#+end_src

- Note :: The state change notes are intentionally put in this test
          LOGBOOK, because we want to ensure that they don't seep into
          the ~notes~ front-matter.
** Extra Front-matter tests                        :extra:verbatim:src_block:
*** Extra Front-matter
:PROPERTIES:
:EXPORT_HUGO_WEIGHT: 5
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :widget "about"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :active "true"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :interests '((interests . ("Artificial Intelligence" "Computational Linguistics" "Information Retrieval")))
:END:
**** TOML Front-matter                                                 :toml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: toml
:END:
***** Extra Front-matter (TOML, TOML extra)                      :toml_extra:
:PROPERTIES:
:EXPORT_FILE_NAME: front-matter-toml-toml-extra
:END:
{{{oxhugoissue(226)}}}

The ~#+begin_src toml :front_matter_extra t~ TOML block here will get
appended to the TOML front-matter.
#+begin_src toml :front_matter_extra t
# List your qualifications (such as academic degrees).
[[education.courses]]
  course = "PhD in Artificial Intelligence"
  institution = "Stanford University"
  year = 2012

[[education.courses]]
  course = "MEng in Artificial Intelligence"
  institution = "Massachusetts Institute of Technology"
  year = 2009

[[education.courses]]
  course = "BSc in Artificial Intelligence"
  institution = "Massachusetts Institute of Technology"
  year = 2008
#+end_src

#+begin_src toml
# this TOML block will export to the Markdown body
#+end_src
***** Extra Front-matter (TOML, YAML extra)                      :yaml_extra:
:PROPERTIES:
:EXPORT_FILE_NAME: front-matter-toml-yaml-extra
:END:
{{{oxhugoissue(226)}}}

The ~#+begin_src yaml :front_matter_extra t~ YAML block here will get
discarded because the front-matter type is TOML.
#+begin_src yaml :front_matter_extra t
education:
  courses:
    - course: PhD in Artificial Intelligence
      institution: Stanford University
      year: 2012
    - course: MEng in Artificial Intelligence
      institution: Massachusetts Institute of Technology
      year: 2009
    - course: BSc in Artificial Intelligence
      institution: Massachusetts Institute of Technology
      year: 2008
#+end_src

#+begin_src toml
# this TOML block will export to the Markdown body
#+end_src
***** ox-hugo Issue 325 test                                     :toml_extra:
:PROPERTIES:
:EXPORT_FILE_NAME: index
:EXPORT_HUGO_SECTION: issues
:EXPORT_HUGO_BUNDLE: 325
:LATEX_TITLE: test 2
:EXPORT_DESCRIPTION: summary of this test.
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :url_pdf "#"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :url_code "#"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :url_dataset "#"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :url_video "#"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :external_link "/courses/example/"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :projects '("signals and systems")
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :image '((caption . " [**Watch**](https://youtube.com)") (preview_only . "true"))
:END:
:LOGBOOK:
CLOCK: [2020-01-29 Wed 16:39]--[2020-01-29 Wed 16:50] =>  0:11
:END:
 <2020-01-29 Wed 16:39>

#+begin_src toml :front_matter_extra t

[[links]]
icon = "youtube"
icon_pack = "fab"
name = "Watch It"
url = "/courses/example/"

[[links]]
icon = "instagram"
icon_pack = "fab"
name = "Inst"
url = "/courses/example/"

[[links]]
icon = "weibo"
icon_pack = "fab"
name = "Weibo"
url = "/courses/example/"

[[links]]
icon = "wechat"
icon_pack = "fab"
name = "Wechat"
url = "/courses/example/"
#+end_src
**** YAML Front-matter                                                 :yaml:
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
***** Extra Front-matter (YAML, YAML extra)                      :yaml_extra:
:PROPERTIES:
:EXPORT_FILE_NAME: front-matter-yaml-yaml-extra
:END:
{{{oxhugoissue(226)}}}

The ~#+begin_src yaml :front_matter_extra t~ YAML block here will get
appended to the YAML front-matter.
#+begin_src yaml :front_matter_extra t
education:
  courses:
    - course: PhD in Artificial Intelligence
      institution: Stanford University
      year: 2012
    - course: MEng in Artificial Intelligence
      institution: Massachusetts Institute of Technology
      year: 2009
    - course: BSc in Artificial Intelligence
      institution: Massachusetts Institute of Technology
      year: 2008
#+end_src

#+begin_src toml
# this TOML block will export to the Markdown body
#+end_src
***** Extra Front-matter (YAML, TOML extra)                      :toml_extra:
:PROPERTIES:
:EXPORT_FILE_NAME: front-matter-yaml-toml-extra
:END:
{{{oxhugoissue(226)}}}

The ~#+begin_src toml :front_matter_extra t~ TOML block here will get
discarded because the front-matter type is YAML.
#+begin_src toml :front_matter_extra t
# List your qualifications (such as academic degrees).
[[education.courses]]
  course = "PhD in Artificial Intelligence"
  institution = "Stanford University"
  year = 2012

[[education.courses]]
  course = "MEng in Artificial Intelligence"
  institution = "Massachusetts Institute of Technology"
  year = 2009

[[education.courses]]
  course = "BSc in Artificial Intelligence"
  institution = "Massachusetts Institute of Technology"
  year = 2008
#+end_src

#+begin_src toml
# this TOML block will export to the Markdown body
#+end_src
* Date and slug inheritance                           :inheritance:date:slug:
:PROPERTIES:
:EXPORT_DATE: 2018-02-12
:EXPORT_HUGO_SLUG: date-and-slug-inheritance
:END:
** Date and slug inheritance (English)
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts/en
:EXPORT_FILE_NAME: date-and-slug-inheritance.en.md
:END:
Date and slug inheritance is useful when you want to use the same data
and slug for multiple posts, but in different languages.

[[/posts/es/data-and-slug-inheritance][Spanish version]]
** Date and slug inheritance (Spanish)
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts/es
:EXPORT_FILE_NAME: date-and-slug-inheritance.es.md
:END:
La herencia de fecha y slug es útil cuando desea usar los mismos datos
y slug para múltiples publicaciones, pero en diferentes idiomas.

[[/posts/en/data-and-slug-inheritance][English version]]
* Issues                                                            :@issues:
:PROPERTIES:
:EXPORT_HUGO_SECTION: issues
:END:
** Issue 335                                                :taxonomy_weight:
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: 335
:EXPORT_HUGO_WEIGHT: :tags 123
:EXPORT_FILE_NAME: index
:END:
#+begin_description
Test the exporting of taxonomy weight parameters like ~tags_weight~.
#+end_description
{{{oxhugoissue(335)}}}
* Real Examples                                               :real_examples:
:PROPERTIES:
:EXPORT_HUGO_SECTION: real-examples
:END:
** Multifractals in ecology using R                          :math:equations:
:PROPERTIES:
:EXPORT_FILE_NAME: multifractals-in-ecology-using-r
:EXPORT_AUTHOR: Leonardo A. Saravia
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :source https://github.com/lsaravia/MultifractalsInR/blob/master/Curso3.md
:EXPORT_DATE: 2017-11-28T10:48:00-05:00
:END:
- Disclaimer :: This post is from the [[https://github.com/lsaravia/MultifractalsInR/blob/master/Curso3.md][link]] posted by GitHub user
                [[https://github.com/lsaravia][*lsaravia*]] in [[https://github.com/gohugoio/hugo/issues/234#issuecomment-347532166][this comment]]. All credit for this post
                goes to the original author.
-----
[[file:/images/MultifractalsInR/fractal-ice.jpg]]
*** Multifractals
- Many natural systems cannot be characterized by a single number such
  as the fractal dimension. Instead an infinite spectrum of dimensions
  must be introduced.

  [[file:/images/MultifractalsInR/C3_Clouds.png]]
*** Multifractal definition
- Consider a given object $\Omega$, its multifractal nature is
  practically determined by covering the system with a set of boxes
  $\{B_i(r)\}$ with $(i=1,..., N(r))$ of side length $r$
- These boxes are nonoverlaping and such that

  $$\Omega = \bigcup_{i=1}^{N(r)} B_i(r)$$

  This is the box-counting method but now a measure $\mu(B_n)$ for each
  box is computed. This measure corresponds to the total population or
  biomass contained in $B_n$, in general will scale as:

  $$\mu(B_n) \propto r^\alpha$$
*** Box counting
[[file:/images/MultifractalsInR/C3_BoxCounting.png]]
*** The generalized dimensions
- The fractal dimension $D$ already defined is actually one of an
  infinite spectrum of so-called correlation dimension of order $q$ or
  also called Renyi entropies.

  $$D_q = \lim_{r \to 0} \frac{1}{q-1}\frac{log \left[ \sum_{i=1}^{N(r)}p_i^q \right]}{\log r}$$

  where $p_i=\mu(B_i)$ and a normalization is assumed:

  $$\sum_{i=1}^{N(r)}p_i=1$$

- For $q=0$ we have the familiar definition of fractal dimension. To see
  this we replace $q=0$

  $$D_0 = -\lim_{r \to 0}\frac{N(r)}{\log r}$$
*** Generalized dimensions 1
- It can be shown that the inequality $D_q' \leq D_q$ holds for
  $q' \geq q$
- The sum

  $$M_q(r) = \sum_{i=1}^{N(r)}[\mu(B_i(r))]^q = \sum_{i=1}^{N(r)}p_i^q$$

  is the so-called moment or partition function of order $q$.
- Varying q allows to measure the non-homogeneity of the pattern. The
  moments with larger $q$ will be dominated by the densest boxes. For
  $q<0$ will come from small $p_i$'s.
- Alternatively we can think that for $q>0$, $D_q$ reflects the scaling
  of the large fluctuations and strong singularities. In contrast, for
  $q<0$, $D_q$ reflects the scaling of the small fluctuations and weak
  singularities.
*** Exercise
- Calculate the partition function for the center and lower images of
  the figure:

  [[file:/images/MultifractalsInR/C3_BoxCounting.png]]
*** Two important dimensions
- Two particular cases are $q=1$ and $q=2$. The dimension for $q=1$ is
  the Shannon entropy or also called by ecologist the Shannon's index of
  diversity.

  $$D_1 = -\lim_{r \to 0}\sum_{i=1}^{N(r)} p_i \log p_i$$

  and the second is the so-called correlation dimension:

  $$D_2 = -\lim_{r \to 0} \frac{\log \left[ \sum_{i=1}^{N(r)} p_i^2 \right]}{\log r} $$

  the numerator is the log of the Simpson index.
*** Application
- Salinity stress in the cladoceran Daphniopsis Australis. Behavioral
  experiments were conducted on individual males, and their successive
  displacements analyzed using the generalized dimension function $D_q$
  and the mass exponent function $\tau_q$

  [[file:/images/MultifractalsInR/C3_Cladoceran.png]]

  both functions indicate that the successive displacements of male D.
  australis have weaker multifractal properties. This is consistent with
  and generalizes previous results showing a decrease in the complexity
  of behavioral sequences under stressful conditions for a range of
  organisms.
- A shift between multifractal and fractal properties or a change in
  multifractal properties, in animal behavior is then suggested as a
  potential diagnostic tool to assess animal stress levels and health.
*** Mass exponent and Hurst exponent
- The same information contained in the generalized dimensions can be
  expressed using mass exponents:

  $$M_q(r) \propto r^{-\tau_q}$$

  This is the scaling of the partition function. For monofractals
  $\tau_q$ is linear and related to the Hurst exponent:

  $$\tau_q = q H - 1$$

  For multifractals we have

  $$\tau_q = (q -1) D_q$$

  Note that for $q=0$, $D_q = \tau_q$ and for $q=1$, $\tau_q=0$
*** Paper
1. Kellner JR, Asner GP (2009) Convergent structural responses of
   tropical forests to diverse disturbance regimes. Ecology Letters 12:
   887--897. doi:10.1111/j.1461-0248.2009.01345.x.
** 神经网络基础    :math:equations:not_english:table:latex:latex_environment:
:PROPERTIES:
:EXPORT_FILE_NAME: nn-intro
:EXPORT_AUTHOR: Feng Ruohang
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :source https://github.com/Vonng/Math/blob/master/nndl/nn-intro.md
:EXPORT_DATE: 2017-11-29
:EXPORT_HUGO_LOCALE: zh
:END:
- Disclaimer :: This post is from the [[https://github.com/Vonng/Math/blob/master/nndl/nn-intro.md][link]] posted by GitHub user
                [[https://github.com/Vonng][*Vonng*]] in [[https://github.com/gohugoio/hugo/issues/234#issuecomment-347725391][this comment]]. All credit for this post
                goes to the original author.
-----
神经网络相关基本知识笔记
*** 神经网络表示
**** 神经元模型
神经网络从大脑的工作原理得到启发，可用于解决通用的学习问题。神经网络的
基本组成单元是 *神经元(neuron)* 。每个神经元具有一个轴突和多个树突。每
个连接到本神经元的树突都是一个输入，当所有输入树突的兴奋水平之和超过某
一阈值，神经元就会被激活。激活的神经元会沿着其轴突发射信号，轴突分出数
以万计的树突连接至其他神经元，并将本神经元的输出并作为其他神经元的输入。
数学上，神经元可以用 *感知机* 的模型表示。

[[file:/images/Vonng/neuron.png]]

一个神经元的数学模型主要包括以下内容：

| 名称                           | 符号 | 说明                               |
|--------------------------------+------+------------------------------------|
| 输入 (input)                   | $x$  | 列向量                             |
| 权值 (weight)                  | $w$  | 行向量，维度等于输入个数           |
| 偏置 (bias)                    | $b$  | 标量值，是阈值的相反数             |
| 带权输入 (weighted input)      | $z$  | $z=w · x + b$ ，激活函数的输入值   |
| 激活函数 (activation function) | $σ$  | 接受带权输入，给出激活值。         |
| 激活值 (activation)            | $a$  | 标量值，$a = σ(\vec{w}·\vec{x}+b)$ |

****** 激活函数表达式
$$
a
= \sigma(
    \left[ \begin{matrix}
        w_{1} & ⋯  & w_{n} \\
    \end{matrix}\right]  ·
    \left[ \begin{array}{x} x_1 \\ ⋮ \\ ⋮ \\ x_n \end{array}\right] +
    b
)
$$

激活函数通常使用S型函数，又称为sigmoid或者logsig，因为该函数具有良好的
特性： *光滑可微* ，形状接近感知机所使用的硬极限传输函数，函数值与 *导
数值计算方便* 。

$$
σ(z) = \frac 1 {1+e^{-z}}
$$

$$
σ'(z) = σ(z)(1-σ(z))
$$

也有一些其他的激活函数，例如：硬极限传输函数(hardlim)，对称硬极限函数(hardlims)，
线性函数(purelin)， 对称饱和线性函数(satlins) ，对数-s形函数(logsig)，正线性函数
(poslin)，双曲正切S形函数(tansig)，竞争函数(compet)，有时候为了学习速度或者其他
原因也会使用，表过不提。
**** 单层神经网络模型
可以并行操作的神经元组成的集合，称为神经网络的一层。

现在考虑一个具有 $n$ 个输入， $s$ 个神经元(输出)的单层神经网络，则原来单个神经元的数
学模型可扩展如下：

| 名称     | 符号 | 说明                                                                 |
|----------+------+----------------------------------------------------------------------|
| 输入     | $x$  | 同层所有神经元共用输入，故输入保持不变，仍为 $(n×1)$ 列向量          |
| 权值     | $W$  | 由 $1 × n$ 行向量，变为 $s × n$ 矩阵，每一行表示一个神经元的权值信息 |
| 偏$置    | $b$  | 由 $1 × 1$ 标量变为 $s × 1$ 列向量                                   |
| 带权输入 | $z$  | 由 $1 × 1$ 标量变为 $s × 1$ 列向量                                   |
| 激活值   | $a$  | 由 $1 × 1$ 标量变为 $s × 1$ 列向量                                   |
****** 激活函数向量表达式
$$
\left[ \begin{array}{a} a_1 \\ ⋮ \\ a_s \end{array}\right]
= \sigma(
    \left[ \begin{matrix}
        w_{1,1} & ⋯  & w_{1,n} \\
        ⋮ & ⋱  & ⋮  \\
        w_{s,1} & ⋯  & w_{s,n} \\
    \end{matrix}\right]  ·
    \left[ \begin{array}{x} x_1 \\ ⋮ \\ ⋮ \\ x_n \end{array}\right] +
    \left[ \begin{array}{b} b_1 \\ ⋮ \\ b_s \end{array}\right]
)
$$

单层神经网络能力有限，通常都会将多个单层神经网络的输出和输入相连，组成
多层神经网络。
**** 多层神经网络模型
- 多层神经网络的层数从1开始计数，第一层为 *输入层* ，第 $L$ 层为 *输出
  层* ，其它的层称为 *隐含层* 。
- 每一层神经网络都有自己的参数 $W,b,z,a,⋯$ ，为了区别，使用上标区分：
  $W^2,W^3,⋯$ 。
- 整个多层网络的输入，即为输入层的激活值 $x=a^1$ ，整个网络的输出，即
  为输出层的激活值： $y'=a^L$ 。
- 因为输入层没有神经元，所以该层所有参数中只有激活值 $a^1$ 作为网络输入
  值而存在，没有 $W^1,b^1,z^1$ 等。

现在考虑一个 $L​$ 层的神经网络，其各层神经元个数依次为：
$d_1,d_2,⋯,d_L​$ 。则该网络的数学模型可扩展如下：

| 名称     | 符号 | 说明                                                                             |
|----------+------+----------------------------------------------------------------------------------|
| 输入     | $x$  | 输入仍然保持不变，为 $(d_1×1)$ 列向量                                            |
| 权值     | $W$  | 由 $s × n$ 矩阵扩展为 $L-1$ 个矩阵组成的列表： $W^2_{d_2 × d_1},⋯,W^L_{d_L × d_{L-1}}$ |
| 偏置     | $b$  | 由 $s × 1$ 列向量扩展为 $L-1$ 个列向量组成的列表： $b^2_{d_2},⋯,b^L_{d_L}$             |
| 带权输入 | $z$  | 由 $s × 1$ 列向量扩展为 $L-1$ 个列向量组成的列表： $z^2_{d_2},⋯,z^L_{d_L}$             |
| 激活值   | $a$  | 由 $s × 1$ 列向量扩展为 *$L$ 个列向量* 组成的列表： $a^1_{d_1},a^2_{d_2},⋯,a^L_{d_L}$     |

****** 激活函数矩阵表达式

$$
\left[ \begin{array}{a} a^l_1 \\ ⋮ \\ a^l_{d_l} \end{array}\right]
= \sigma(
    \left[ \begin{matrix}
        w^l_{1,1} & ⋯  & w^l_{1,d_{l-1}} \\
        ⋮ & ⋱  & ⋮  \\
        w^l_{d_l,1} & ⋯  & w^l_{d_l,d_{l-1}} \\
    \end{matrix}\right]  ·
    \left[ \begin{array}{x} a^{l-1}_1 \\ ⋮ \\ ⋮ \\ a^{l-1}_{d_{l-1}} \end{array}\right] +
    \left[ \begin{array}{b} b^l_1 \\ ⋮ \\ b^l_{d_l} \end{array}\right])
$$

***** 权值矩阵的涵义
多层神经网络的权值由一系列权值矩阵表示

- 第 $l$ 层网络的权值矩阵可记作 $W^l$ ，表示前一层（ $l-1$ ）到本层
  （$l$）的连接权重
- $W^l$ 的第 $j$ 行可记作 $W^l_{j*}$
  ，表示从 $l-1$ 层所有 $d_{l-1}$ 个神经元出发，到达 $l$
  层 $j$ 号神经元的连接权重
- $W^l$ 的第 $k$ 列可记作 $W^l_{*k}$
  ，表示从 $l-1$ 层第 $k$ 号神经元出发，到达 $l$
  层所有 $d_l$ 个神经元的连接权重
- $W^l$ 的 $j$ 行 $k$ 列可记作 $W^l_{jk}$ ，表示从 $l-1$ 层 $k$ 号神经元
  出发，到达 $l$ 层 $j$ 神经元的连接权重
- 如图， $w^3_{24}$ 表示从2层4号神经元到3层2号神经元的连接权值：

[[file:/images/Vonng/nn-weight.png]]

只要记住，权值矩阵 $W$ 的 *行标表示本层神经元* 的标号， *列标表示上层
神 经元* 的标号即可。

*** 神经网络推断
*前馈（feed forward）* 是指神经网络接受输入，产生输出的一次计算过程。又
称为一次 *推断（inference）* 。

计算过程如下：

\begin{align}
a^1  &= x \\
a^2  &=  σ(W^2a^1 + b^2) \\
a^3  &=  σ(W^3a^2 + b^3) \\
⋯ \\
a^L  &= σ(W^La^{L-1} + b^L) \\
y  &= a^L \\
\end{align}

推断实际上就是一系列矩阵乘法与向量运算，一个训练好的神经网络可以高效地
使用各种语言实现。神经网络的功能是通过推断而体现的。推断实现起来很简单，
但如何 *训练神经网络* 才是真正的难点。

*** 神经网络训练
神经网络的训练，是调整网络中的权值参数与偏置参数，从而提高网络工作效果
的过程。

通常使用 *梯度下降(Gradient Descent)* 的方法来调整神经网络的参数，首先
要定义一个 *代价函数(cost function)* 用以衡量神经网络的误差，然后通过
梯度下降方法计算合适的参数修正量，从而 *最小化* 网络误差。
**** 代价函数
代价函数是用于衡量神经网络工作效果的函数，是定义在一个或多个样本上的实
值函数，通常应满足以下条件：

1. *误差是非负的，神经网络效果越好，误差越小*
2. *代价可以写成神经网络输出的函数*
3. *总体代价等于个体样本代价的均值* ： $C=\frac{1}{n} \sum_x C_x$

最常用的一个简单的代价函数是： *二次代价函数* ，又称为 *均方误差
(MeanSquareError)*

$$
C(w,b) = \frac{1}{2n} \sum_x{{\|y(x)-a\|}^2}
$$

前面的系数 $\frac 1 2$ 是为了求导后简洁的形式而添加的， $n$ 是使用样本
的数量，这里 $y$  和 $x$ 都是已知的样本数据。

理论上任何可以反映网络工作效果的指标都可以作为代价函数。但之所以使用
MSE，而不是诸如"正确分类图像个数"的指标，是因为只有一个 *光滑可导* 的
代价函数才可以使用 *梯度下降* (Gradient Descent)调整参数。

***** 样本的使用
代价函数的计算需要一个或多个训练样本。当训练样本非常多时，如果每轮训练
都要重新计算网络整个训练集上所有样本的误差函数，开销非常大，速度难以接
受。若只使用总体的一小部分，计算就能快很多。不过这样做依赖一个假设：
*随机样本的代价，近似等于总体的代价。*

按照使用样本的方式，梯度下降又分为：

- 批量梯度下降法(Batch GD)：最原始的形式，更新每一参数都使用所有样本。可以得到全
  局最优解，易于并行实现，但当样本数量很多时，训练速度极慢。

- 随机梯度下降法(Stochastic GD)：解决BGD训练慢的问题，每次随机使用一个样本。训练
  速度快，但准确度下降，且并不是全局最优，也不易于并行实现。
- 小批量梯度下降法(MiniBatch GD)：在每次更新参数时使用b个样本（例如每次10个样本），
  在BGD与SGD中取得折中。

每次只使用一个样本时，又称为在线学习或递增学习。

当训练集的所有样本都被使用过一轮，称为完成一轮 *迭代* 。

**** 梯度下降算法
若希望通过调整神经网络中的某个参数来减小整体代价，则可以考虑微分的方法。
因为每层的激活函数，以及最终的代价函数都是光滑可导的。所以最终的代价函
数 $C$ 对于某个我们感兴趣的参数 $w,b$ 也是光滑可导的。轻微拨动某个参数
的值，最终的误差值也会发生连续的轻微的变化。不断地沿着参数的梯度方向，
轻微调整每个参数的值，使得总误差值向下降的方向前进，最终达到极值点。就
是梯度下降法的核心思想。
***** 梯度下降的逻辑
现在假设代价函数 $C$ 为两个变量 $v_1,v_2$ 的可微函数，梯度下降实际上就是
选择合适的 $Δv$ ，使得 $ΔC$ 为负。由微积分可知：

$$
ΔC ≈ \frac{∂C}{∂v_1} Δv_1 + \frac{∂C}{∂v_2} Δv_2
$$

这里 $Δv$ 是向量： $Δv = \left[ \begin{array}{v} Δv_1 \\ Δv_2
\end{array}\right]$ ， $∇C$  是梯度向量 $\left[ \begin{array}{C}
\frac{∂C}{∂v_1} \\ \frac{∂C}{∂v_2} \end{array} \right]$ ，于是上式可重
写为

$$
ΔC ≈ ∇C·Δv
$$

怎样的 $Δv$ 才能令代价函数的变化量为负呢？一种简单办法是令即 $Δv$ 取一
个与梯度 $∇C$ 共线反向的小向量，此时 $Δv = -η∇C$ ，则损失函数变化量
$ΔC ≈ -η{∇C}^2$ ，可以确保为负值。按照这种方法，通过不断调整  $v$ ： $v
→ v' = v -η∇C$ ，使得 $C$ 最终达到极小值点。

这即梯度下降的涵义所在： *所有参数都会沿着自己的梯度(导数)方向不断进行
轻微下降， 使得总误差到达极值点。*

对于神经网络，学习的参数实际上是权重 $w$ 与偏置量 $b$ 。原理是一样的，不过这里的
 $w,b$ 数目非常巨大

$$
w →w' = w-η\frac{∂C}{∂w} \\
b → b' = b-η\frac{∂C}{∂b}
$$

真正棘手的问题在于梯度 $∇C_w,∇C_b$ 的计算方式。如果使用微分的方法，通
过 $\frac {C(p+ε)-C} {ε}$ 来求参数的梯度，那么网络中的每一个参数都需要
进行一次前馈和一次 $C(p+ε)$  的计算，在神经网络汪洋大海般的参数面前，这
样的办法是行不通的。

*反向传播(Back propagation)算法* 可以解决这一问题。通过巧妙的简化，可
以在一次前馈与一次反传中，高效地计算整个网络中所有参数梯度。

*** 反向传播
反向传播算法接受一个打标样本 $(x,y)$ 作为输入，给出网络中所有参数 $(W,b)$ 的梯度。

**** 反向传播误差δ
反向传播算法需要引入一个新的概念：误差 $δ$ 。误差的定义源于这样一种朴素的思想：如
果轻微修改某个神经元的带权输入 $z$ ，而最终代价 $C$ 已不再变化，则可认为 $z$ 已经到达
极值点，调整的很好了。于是损失函数 $C$ 对某神经元带权输入 $z$ 的偏导 $\frac {∂C}{∂z}$
可以作为该神经元上误差 $δ$ 的度量。故定义第 $l$ 层的第 $j^{th}$ 个神经元上的误差 $δ^l_j$ 为：

$$
δ^l_j ≡ \frac{∂C}{∂z^l_j}
$$

与激活值 $a$ ， 带权输入 $z$ 一 样，误差也可以写作向量。第 $l$ 层 的误差向量记作 $δ^l$ 。 虽
然看上去差不多，但之所以使用带权输入 $z$ 而 不是激活值输出 $a$ 来 定义本层的误差，有着
形式上巧妙的设计。

引入反向传播误差的概念，是为了通过误差向量来计算梯度 $∇C_w,∇C_b$ 。

反向传播算法一言蔽之：计算出 *输出层误差* ，通过递推方程逐层回算出 *每
一层的误差* ，再由每一层的误差算出 *本层的权值梯度与偏置梯度* 。

这需要解决四个问题：

1. 递推首项：如何计算输出层的误差： $δ^L$
2. 递推方程：如何根据后一层的误差 $δ^{l+1}$ 计 算前一层误差 $δ^l$
3. 权值梯度：如何根据本层误差 $δ^l$ 计 算本层权值梯度 $∇W^l$
4. 偏置梯度：如何根据本层误差 $δ^l$ 计 算本层偏置梯度 $∇b^l$

这四个问题，可以通过四个反向传播方程得到解决。

**** 反向传播方程
| 方程                            | 说明               | 编号 |
|---------------------------------+--------------------+------|
| $δ^L = ∇C_a ⊙ σ'(z^L)$          | 输出层误差计算公式 | BP1  |
| $δ^l = (W^{l+1})^T δ^{l+1} ⊙ σ'(z^l)$ | 误差传递公式       | BP2  |
| $∇C_{W^l} = δ^l × {(a^{{l-1})}}T$     | 权值梯度计算公式   | BP3  |
| $∇C_b = δ^l$                    | 偏置梯度计算公式   | BP4  |

当误差函数取MSE： $C = \frac 1 2 \|\vec{y} -\vec{a}\|^2= \frac 1 2
[(y_1 - a_1)^2 + \cdots + (y_{d_L} - a_{d_L})^2]$ ，激活函数取sigmoid时：

| 计算方程                             | 说明                                                              | 编号 |
|--------------------------------------+-------------------------------------------------------------------+------|
| $δ^L = (a^L - y) ⊙(1-a^L)⊙ a^L$      | 输出层误差需要 $a^L$ 和 $y$                                       | BP1  |
| $δ^l = (W^{{l+1})}T δ^{l+1} ⊙(1-a^l)⊙ a^l$ | 本层误差需要：后层权值 $W^{l+1}$ ， 后层误差 $δ^{l+1}$ ， 本层输出$a^l$ | BP2  |
| $∇C_{W^l} = δ^l × {(a^{{l-1})}}T$          | 权值梯度需要：本层误差 $δ^l$ ， 前层输出$a^{l-1}$                    | BP3  |
| $∇C_b = δ^l$                         | 偏置梯度需要：本层误差$δ^l$                                       | BP4  |

**** 反向传播方程的证明
***** BP1：输出层误差方程
输出层误差方程给出了根据网络输出 $a^L$ 与 标记结果 $y$ 计 算输出层误差 $δ$ 的 方法：

$$
δ^L = (a^L - y) ⊙(1-a^L)⊙ a^L
$$

****** 证明
因为 $a^L = σ(z^L)$ ，本方程可以直接从反向传播误差的定义，通过 *$a^L$
作为中间变量链 式求导* 推导得出：

$$
\frac{∂C}{∂z^L} = \frac{∂C}{∂a^L} \frac{∂a^L}{∂z^L}  = ∇C_a σ'(z^L)
$$

而因为误差函数 $C = \frac 1 2 \|\vec{y} -\vec{a}\|^2= \frac 1 2
[(y_1 - a_1)^2 + ⋯ + (y_{d_L} - a_{d_L})^2]$ ，方程两侧对某个 $a_j$ 取偏导则
有：

$$
\frac {∂C}{∂a^L_j} = (a^L_j-y_j)
$$

因为误差函数中，其他神经元的输出不会影响到误差函数对神经元 $j$ 输出的
偏导，系数也正好平掉了。写作向量形式即为： $(a^L - y)$ 。另一方面，易
证 $σ'(z^L) = (1-a^L)⊙ a^L$ 。

QED
***** BP2：误差传递方程
误差传递方程给出了根据后一层误差计算前一层误差的方法：

$$
δ^l = (W^{l+1})^T δ^{l+1} ⊙ σ'(z^l)
$$

****** 证明
本方程可以直接从反向传播误差的定义，以后一层所有神经元的带权输入 $z^{l+1}$ 作 为中间变
量进行链式求导推导出：

$$
δ^l_j = \frac {∂C}{∂z^l_j}
= \sum_{k=1}^{d_{l+1}}  \frac{∂C}{∂z^{l+1}_k} \frac{∂z^{l+1}_k}{∂z^{l}_j}
= \sum_{k=1}^{d_{l+1}}  (δ^{l+1}_k  \frac{∂z^{l+1}_k}{∂z^{l}_j})
$$

通过链式求导，引入后一层带权输入作为中间变量，从而在方程右侧引入后一层
误差的表达形式。现在要解决的就是 $\frac{∂z^{l+1}_k}{∂z^{l}_j}​$ 是 什么的问
题。由带权输入的定义 $z = wx + b​$ 可知：

$$
z^{l+1}_k = W^{l+1}_{k,*} ·a^l + b^{l+1}_{k}  =   W^{l+1}_{k,*} · σ(z^{l}) + b^{l+1}_{k}
= \sum_{j=1}^{d_{l}}(w_{kj}^{l+1} σ(z^{l_j})) + b^{l+1}_{k}
$$

两边同时对 $z^{l}_j$ 求 导可以得到：

$$
\frac{∂z^{l+1}_k}{∂z^{l}_j} = w^{l+1}_{kj} σ'(z^l)
$$

回代则有：

\begin{align}
δ^l_j & = \sum_{k=1}^{d_{l+1}}  (δ^{l+1}_k  \frac{∂z^{l+1}_k}{∂z^{l}_j})  \\
& = σ'(z^l)   \sum_{k=1}^{d_{l+1}}     (δ^{l+1}_k  w^{l+1}_{kj}) \\
& = σ'(z^l) ⊙  [(δ^{l+1}) · W^{l+1}_{*.j}] \\
& = σ'(z^l) ⊙ [(W^{l+1})^T_{j,*} ·  (δ^{l+1}) ]\\
\end{align}

这里，对后一层所有神经元的误差权值之积求和，可以改写为两个向量的点积：

- 后一层 $k$ 个 神经元的误差向量
- 后一层权值矩阵的第 $j$ 列 ，即所有从本层 $j$ 神 经元出发前往下一层所有 $k$ 个 神经元的
  权值。

又因为向量点积可以改写为矩阵乘法：以行向量乘以列向量的方式进行，所以将权值矩阵转
置，原来拿的是列，现在则拿出了行向量。这时候再改写回向量形式为：

$$
δ^l =  σ'(z^l) ⊙ (W^{l+1})^Tδ^{l+1}
$$

QED
***** BP3：权值梯度方程
每一层的权值梯度 $∇C_{W^l}$ 可 以根据本层的误差向量（列向量），与上层的输出向量（行向
量）的外积得出。

$$
∇C_{W^l} = δ^l × {(a^{l-1})}^T
$$

****** 证明
由误差的定义，以 $w^l_{jk}$ 作 为中间变量求偏导可得：

\begin{align}
δ^l_j & = \frac{∂C}{∂z^l_j}
= \frac{∂C}{∂w^l_{jk}} \frac{∂ w_{jk}}{∂ z^l_j}
= ∇C_{w^l_{jk}} \frac{∂w_{jk}}{∂ z^l_j}
\end{align}

由定义可得，第 $l$ 层 第 $j$ 个 神经元的带权输入 $z^l_j$ ：

$$
z^l_j = \sum_k w^l_{jk} a^{l-1}_k + b^l_j
$$

两侧对 $w_{jk}^l$ 求 导得到：

$$
\frac{\partial z_j}{\partial w^l_{jk}} = a^{l-1}_k
$$

代回则有： $$
∇C_{w^l_{jk}} = δ^l_j \frac{∂ z^l_j}{∂w_{jk}} =   δ^l_j a^{l-1}_k
$$ 观察可知，向量形式是一个外积： $$
∇C_{W^l} = δ^l × {(a^{l-1})}^T
$$

- *本层误差行向量* ： $δ^l$ ，维度为（$d_l \times 1$)

- *上层激活列向量* ： $(a^{l-1})^T​$ ，维度为（$1 \times d_{l-1}​$）

QED
***** BP4：偏置梯度方程
$$
∇C_b = δ^l
$$

****** 证明
由定义可知：

$$
δ^l_j  = \frac{∂C}{∂z^l_j}
= \frac{∂C}{∂b^l_j} \frac{∂b_j}{∂z^l_j}
= ∇C_{b^l_{j}} \frac{∂b_j}{∂z^l_j}
$$

因为 $z^l_j = W^l_{*,j} \cdot a^{l-1} + b^l_j$ ，两侧对 $z_j^l$ 求 导得到
$1=\frac{∂b_j}{∂z^l_j}$ 。 于是回代得到： $∇C_{b^l_{j}} =δ^l_j$ ，

QED

至此，四个方程均已证毕。只要将其转换为代码即可工作。
*** 神经网络的实现
作为概念验证，这里给出了MNIST手写数字分类神经网络的Python实现。

#+begin_src python
# coding: utf-8
# author: vonng(fengruohang@outlook.com)
# ctime: 2017-05-10

import random
import numpy as np

class Network(object):
    def __init__(self, sizes):
        self.sizes = sizes
        self.L = len(sizes)
        self.layers = range(0, self.L - 1)
        self.w = [np.random.randn(y, x) for x, y in zip(sizes[:-1], sizes[1:])]
        self.b = [np.random.randn(x, 1) for x in sizes[1:]]

    def feed_forward(self, a):
        for l in self.layers:
            a = 1.0 / (1.0 + np.exp(-np.dot(self.w[l], a) - self.b[l]))
        return a

    def gradient_descent(self, train, test, epoches=30, m=10, eta=3.0):
        for round in range(epoches):
            # generate mini batch
            random.shuffle(train)
            for batch in [train_data[k:k + m] for k in xrange(0, len(train), m)]:
                x = np.array([item[0].reshape(784) for item in batch]).transpose()
                y = np.array([item[1].reshape(10) for item in batch]).transpose()
                n, r, a = len(batch), eta / len(batch), [x]

                # forward & save activations
                for l in self.layers:
                    a.append(1.0 / (np.exp(-np.dot(self.w[l], a[-1]) - self.b[l]) + 1))

                # back propagation
                d = (a[-1] - y) * a[-1] * (1 - a[-1])   #BP1
                for l in range(1, self.L):  # l is reverse index since last layer
                    if l > 1:   #BP2
                        d = np.dot(self.w[-l + 1].transpose(), d) * a[-l] * (1 - a[-l])
                    self.w[-l] -= r * np.dot(d, a[-l - 1].transpose()) #BP3
                    self.b[-l] -= r * np.sum(d, axis=1, keepdims=True) #BP4

            # evaluate
            acc_cnt = sum([np.argmax(self.feed_forward(x)) == y for x, y in test])
            print "Round {%d}: {%s}/{%d}" % (round, acc_cnt, len(test_data))


if __name__ == '__main__':
    import mnist_loader

    train_data, valid_data, test_data = mnist_loader.load_data_wrapper()
    net = Network([784, 100, 10])
    net.gradient_descent(train_data, test_data, epoches=100, m=10, eta=2.0)
#+end_src

数据加载脚本： [[https://github.com/mnielsen/neural-networks-and-deep-learning/blob/master/src/mnist_loader.py][=mnist_loader.py=]]
。输入数据为二元组列表： =(input(784,1), output(10,1))=

#+begin_src sh
$ python net.py
Round {0}: {9136}/{10000}
Round {1}: {9265}/{10000}
Round {2}: {9327}/{10000}
Round {3}: {9387}/{10000}
Round {4}: {9418}/{10000}
Round {5}: {9470}/{10000}
Round {6}: {9469}/{10000}
Round {7}: {9484}/{10000}
Round {8}: {9509}/{10000}
Round {9}: {9539}/{10000}
Round {10}: {9526}/{10000}
#+end_src

一轮迭代后，网络在测试集上的分类准确率就达到90%，最终收敛至96%左右。

对于五十行代码，这个效果是值得惊叹的。然而96%的准确率在实际生产中恐怕仍然是无法
接受的。想要达到更好的效果，就需要对神经网络进行优化。

*** 神经网络优化
神经网络的基础知识也就这么多，但优化其表现却是一个无尽的挑战。每一种优化的手段都
可以当做一个进阶的课题深入研究。优化手段也是八仙过海各显神通：有数学，有科学，有
工程学，也有哲学，还有玄学...

改进神经网络的学习效果有几种主要的方法：

- 选取 *更好的代价函数* ：例如 *交叉熵（cross-entropy）*
- *规范化（regularization）* ： *L2规范化* 、弃权、L1规范化
- 采用其他的 *激活神经元* ：线性修正神经元（ReLU），双曲正切神经元（tansig）
- 修改神经网络的输出层： *柔性最大值(softmax)*
- 修改神经网络输入的组织方式：递归神经网络（Recurrent
  NN），卷积神经网络（Convolutional NN）。
- 添加层数：深度神经网络（Deep NN）
- 通过尝试，选择合适的 *超参数（hyper-parameters）* ，按照迭代轮数或评
  估效果动态调整超参数。
- 采用其他的梯度下降方法：基于动量的梯度下降
- 使用更好的 *初始化权重*
- 人为扩展已有训练数据集

这里介绍两种方法， *交叉熵代价函数* 与 *L2规范化* 。因为它们：

- 实现简单，修改一行代码即可实现，还减小了计算开销。
- 效果立竿见影，将分类错误率从4%降低到2%以下。

**** 代价函数：交叉熵
MSE是一个不错的代价函数，然而它存在一个很尴尬的问题：学习速度。

MSE输出层误差的计算公式为： $$
δ^L =  (a^L - y)σ'(z^L)
$$

sigmoid又称为逻辑斯蒂曲线，其导数 $σ'$ 是 一个钟形曲线。所以当带权输入 $z$ 从 大到小或
从小到大时，梯度的变化会经历一个"小，大，小"的过程。学习的速度也会被导数项拖累，
存在一个"慢，快，慢"的过程。

| MSE                       | Cross Entropy                       |
|---------------------------+-------------------------------------|
| [[file:/images/Vonng/mse.png]] | [[file:/images/Vonng/cross-entropy.png]] |

若采用 *交叉熵（cross entropy）* 误差函数：

$$
C = - \frac 1 n \sum_x [ y ln(a) + (1-y)ln(1-a)]
$$

对于单个样本，即

$$
C = - [ y ln(a) + (1-y)ln(1-a)]
$$

虽然看起来很复杂，但输出层的误差公式变得异常简单，变为： $δ^L = a^L - y$

比起MSE少掉了导数因子，所以误差直接和（预测值-实际值）成正比，不会遇到学习速度被
激活函数的导数拖慢的问题，计算起来也更为简单。

***** 证明
$C$ 对 网络输出值 $a$ 求 导，则有：

$$
∇C_a = \frac {∂C} {∂a^L} = - [ \frac y a - \frac {(1-y)} {1-a}] = \frac {a - y} {a (1-a)}
$$

反向传播的四个基本方程里，与误差函数 $C$ 相 关的只有BP1：即输出层误差的计算方式。

$$
δ^L = ∇C_a ⊙ σ'(z^L)
$$

现在 $C$ 换 了计算方式，将新的误差函数 $C$ 对 输出值 $a^L$ 的 梯度
$\frac {∂C} {∂a^L}$ 带回BP1，即有：

$$
δ^L = \frac {a - y} {a (1-a)}× a(1-a) = a-y
$$

**** 规范化
拥有大量的自由参数的模型能够描述特别神奇的现象。

费米说："With four parameters I can fit an elephant, and with five I can make
him wiggle his trunk"。神经网络这种动辄百万的参数的模型能拟合出什么奇妙的东西是
难以想象的。

一个模型能够很好的拟合已有的数据，可能只是因为模型中足够的自由度，使得
它可以描述几乎所有给定大小的数据集，而不是真正洞察数据集背后的本质。发
生这种情形时， *模型对已有的数据表现的很好，但是对新的数据很难泛化* 。
这种情况称为 *过拟合（overfitting）* 。

例如用3阶多项式拟合一个带随机噪声的正弦函数，看上去就还不错；而10阶多项式，虽然
完美拟合了数据集中的所有点，但实际预测能力就很离谱了。它拟合的更多地是数据集中的
噪声，而非数据集背后的潜在规律。

#+begin_src python
x, xs = np.linspace(0, 2 * np.pi, 10), np.arange(0, 2 * np.pi, 0.001)
y = np.sin(x) + np.random.randn(10) * 0.4
p1,p2 = np.polyfit(x, y, 10), np.polyfit(x, y, 3)
plt.plot(xs, np.polyval(p1, xs));plt.plot(x, y, 'ro');plt.plot(xs, np.sin(xs), 'r--')
plt.plot(xs, np.polyval(p2, xs));plt.plot(x, y, 'ro');plt.plot(xs, np.sin(xs), 'r--')
#+end_src

| 3阶多项式                        | 10阶多项式                        |
|----------------------------------+-----------------------------------|
| [[file:/images/Vonng/overfit-3.png]] | [[file:/images/Vonng/overfit-10.png]] |

一个模型真正的测验标准，是它对没有见过的场景的预测能力，称为 *泛化能力
（generalize）* 。

如何避免过拟合？按照奥卡姆剃刀原理： *两个效果相同的解释，选择简单的那
一个。*

当然这个原理只是我们抱有的一种信念，并不是真正的定理铁律：这些数据点真的由拟合出
的十阶多项式产生，也不能否认这种可能...

总之，如果出现非常大的权重参数，通常就意味着过拟合。例如拟合所得十阶多项式系数就
非常畸形：

#+begin_example
-0.001278386964370502
0.02826407452052734
-0.20310716176300195
0.049178327509096835
7.376259706365357
-46.295365250182925
135.58265224859255
-211.767050023543
167.26204130954324
-50.95259728945658
0.4211227089756039
#+end_example

通过添加权重衰减项，可以有效遏制过拟合。例如 $L2$ 规 范化为损失函数添
加了一个 $\frac λ 2 w^2$ 的惩罚项：

$$
C = -\frac{1}{n} \sum_{xj} \left[ y_j \ln a^L_j+(1-y_j) \ln
  (1-a^L_j)\right] + \frac{\lambda}{2n} \sum_w w^2
$$

所以，权重越大，损失值越大，这就避免神经网络了向拟合出畸形参数的方向发展。

这里使用的是交叉熵损失函数。但无论哪种损失函数，都可以写成：

$$
C = C_0 + \frac {λ}{2n} \sum_w {w^2}
$$

其中原始的代价函数为 $C_0$ 。 那么，原来损失函数对权值的偏导，就可以写成：

$$
\frac{∂C}{∂w} = \frac{ ∂C_0}{∂w}+\frac{λ}{n} w
$$

因此，引入 $L2$ 规 范化惩罚项在计算上的唯一变化，就是在处理权值梯度时首先要乘一个衰
减系数：

$$
w → w' = w\left(1 - \frac{ηλ}{n} \right) - η\frac{∂C_0}{∂ w}
$$

注意这里的 $n$ 是 所有的训练样本数，而不是一个小批次使用的训练样本数。

***** 改进实现
#+begin_src python
# coding: utf-8
# author: vonng(fengruohang@outlook.com)
# ctime: 2017-05-10

import random
import numpy as np

class Network(object):
    def __init__(self, sizes):
        self.sizes = sizes
        self.L = len(sizes)
        self.layers = range(0, self.L - 1)
        self.w = [np.random.randn(y, x) / np.sqrt(x) for x, y in zip(sizes[:-1], sizes[1:])]
        self.b = [np.random.randn(x, 1) for x in sizes[1:]]

    def feed_forward(self, a):
        for l in self.layers:
            a = 1.0 / (1.0 + np.exp(-np.dot(self.w[l], a) - self.b[l]))
        return a

    def gradient_descent(self, train, test, epoches=30, m=10, eta=0.1, lmd=5.0):
        n = len(train)
        for round in range(epoches):
            random.shuffle(train)
            for batch in [train_data[k:k + m] for k in xrange(0, len(train), m)]:
                x = np.array([item[0].reshape(784) for item in batch]).transpose()
                y = np.array([item[1].reshape(10) for item in batch]).transpose()
                r = eta / len(batch)
                w = 1 - eta * lmd / n

                a = [x]
                for l in self.layers:
                    a.append(1.0 / (np.exp(-np.dot(self.w[l], a[-1]) - self.b[l]) + 1))

                d = (a[-1] - y)  # cross-entropy    BP1
                for l in range(1, self.L):
                    if l > 1:   # BP2
                        d = np.dot(self.w[-l + 1].transpose(), d) * a[-l] * (1 - a[-l])
                    self.w[-l] *= w  # weight decay
                    self.w[-l] -= r * np.dot(d, a[-l - 1].transpose())  # BP3
                    self.b[-l] -= r * np.sum(d, axis=1, keepdims=True)  # BP4

            acc_cnt = sum([np.argmax(self.feed_forward(x)) == y for x, y in test])
            print "Round {%d}: {%s}/{%d}" % (round, acc_cnt, len(test_data))


if __name__ == '__main__':
    import mnist_loader
    train_data, valid_data, test_data = mnist_loader.load_data_wrapper()
    net = Network([784, 100, 10])
    net.gradient_descent(train_data, test_data, epoches=50, m=10, eta=0.1, lmd=5.0)
#+end_src

#+begin_example
Round {0}: {9348}/{10000}
Round {1}: {9538}/{10000}
Round {2}: {9589}/{10000}
Round {3}: {9667}/{10000}
Round {4}: {9651}/{10000}
Round {5}: {9676}/{10000}
...
Round {25}: {9801}/{10000}
Round {26}: {9799}/{10000}
Round {27}: {9806}/{10000}
Round {28}: {9804}/{10000}
Round {29}: {9804}/{10000}
Round {30}: {9802}/{10000}
#+end_example

可见只是简单的变更，就使准确率有了显著提高，最终收敛至98%。

修改Size为 =[784,128,64,10]= 添加一层隐藏层，可以进一步提升测试集准确
率至98.33%，验证集至98.24%。

对于MNIST数字分类任务，目前最好的准确率为99.79%，那些识别错误的case，恐怕人类想
要正确识别也很困难。神经网络的分类效果最新进展可以参看这里：
[[http://rodrigob.github.io/are_we_there_yet/build/classification_datasets_results.html][classification\_datasets\_results]]。

本文是tensorflow官方推荐教程：[[http://neuralnetworksanddeeplearning.com/][Neural Networks and Deep Learning]]的笔记整理，原文
[[https://github.com/Vonng/Math/blob/master/nndl/nn-intro.md][Github Page]]。
* Testing Draft state                                                 :draft:
** TODO Pre-Draft State
:PROPERTIES:
:EXPORT_FILE_NAME: draft-state-todo
:EXPORT_DATE: 2017-07-12T17:05:41-04:00
:END:
If a post has the =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.
** HUGO_DRAFT set to true
:PROPERTIES:
:EXPORT_HUGO_DRAFT: true
:END:
The value of ~EXPORT_HUGO_DRAFT~ state property should have no effect
if an Org TODO state is set for the post subtree.
*** DRAFT HUGO_DRAFT true, DRAFT state                                 :todo:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-true-todo-state-draft
:END:
If a post has the Org TODO state set to =DRAFT=, the =draft= front
matter variable should be set to =true= regardless of the value of
~EXPORT_HUGO_DRAFT~ property.

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
*** DONE HUGO_DRAFT true, DONE state (Override)          :todo:done:override:
CLOSED: [2018-07-09 Mon 10:38]
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-true-todo-state-done
:END:
This post has ~EXPORT_HUGO_DRAFT~ set to ~"true"~. But the *DONE*
state of Org TODO overrides that.
*** HUGO_DRAFT true, no TODO state                                 :property:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-true-todo-state-none
:END:
This post does not have any Org TODO state. So it uses the value of
~EXPORT_HUGO_DRAFT~.
** HUGO_DRAFT set to false
:PROPERTIES:
:EXPORT_HUGO_DRAFT: false
:END:
The value of ~EXPORT_HUGO_DRAFT~ state property should have no effect
if an Org TODO state is set for the post subtree.
*** DRAFT HUGO_DRAFT false, DRAFT state (Override)            :todo:override:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-false-todo-state-draft
:END:
This post has ~EXPORT_HUGO_DRAFT~ set to ~"false"~. But the *DRAFT*
state of Org TODO overrides that.
*** DONE HUGO_DRAFT false, DONE state                             :todo:done:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-false-todo-state-done
:END:
The *DONE* state of Org TODO sets ~draft~ to ~false~ for this post.
*** HUGO_DRAFT false, no TODO state                                :property:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-false-todo-state-none
:END:
This post does not have any Org TODO state. So it uses the value of
~EXPORT_HUGO_DRAFT~.
** HUGO_DRAFT not set
*** DRAFT HUGO_DRAFT not set, DRAFT state                              :todo:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-none-todo-state-draft
:END:
This post is marked as draft as the Org TODO state is set to ~DRAFT~.
*** TEST__TODO HUGO_DRAFT not set, TEST__TODO state               :todo:test:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-none-todo-state-test-todo
:END:
This post is marked as draft as the Org TODO state is set to
~TEST__TODO~.
*** DONE HUGO_DRAFT not set, DONE state                           :todo:done:
CLOSED: [2018-07-09 Mon 11:00]
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-none-todo-state-done
:END:
This post is not marked as draft as the Org TODO state is set to
~DONE~.
*** TEST__DONE HUGO_DRAFT not set, TEST__DONE state          :todo:done:test:
CLOSED: [2018-07-10 Tue 10:42]
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-none-todo-state-test-done
:END:
This post is not marked as draft as the Org TODO state is set to
~TEST__DONE~.
*** HUGO_DRAFT not set, no TODO state either                        :default:
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-draft-none-todo-state-none
:END:
This post has neither the ~EXPORT_HUGO_DRAFT~ property set, nor the
Org TODO state. So the draft state defaults to /false/.
** DRAFT Draft state with other headlines :post_heading_followed_soon_with_subheading:
:PROPERTIES:
:EXPORT_FILE_NAME: draft-state-other-headings-draft
:EXPORT_DATE: 2017-07-12T13:46:16-04:00
:END:
*** The "TODO" state of this heading (which is nil) should be ignored
If a post has the =DRAFT= state set, the =draft= front matter variable
should be set to =true=, even if the post has a sub-heading
immediately after the post heading.
* Illegal cases                        :illegal:dont_export_during_make_test:
** Subtree with empty EXPORT_FILE_NAME       :subtree:empty:export_file_name:
:PROPERTIES:
:EXPORT_FILE_NAME:
:END:
#+begin_description
This subtree must not export because the EXPORT_FILE_NAME is empty.
#+end_description
{{{oxhugoissue(211)}}}
* Reusable sections                                        :noexport:ARCHIVE:
** Quote block with source block, followed by source block
:PROPERTIES:
:CUSTOM_ID: quote-blk-with-src-block--followed-by-src
:END:
#+begin_quote
Some quoted text.
#+begin_src emacs-lisp
(message "hello")
#+end_src
#+end_quote
#+begin_src emacs-lisp
(message "hello again")
#+end_src
** Summary portion in <details> element
:PROPERTIES:
:CUSTOM_ID: details-disclosure-summary
:END:
Here is the *summary*.

While normally summaries wouldn't be across multiple paragraphs, we
are testing it that way as HTML supports that.

#+begin_src emacs-lisp
(message
 (concat "This is part of the summary too.. "
         "just click anywhere in the summary to expand it."))
#+end_src
** Details portion in <details> element
:PROPERTIES:
:CUSTOM_ID: details-disclosure-details
:END:
Here are some /details/.

- list element 1
- list element 2

Here's a paragraph.

And another paragraph.

#+begin_src emacs-lisp
(message "a code block")
#+end_src
** Nested sections example
:PROPERTIES:
:CUSTOM_ID: nested-sections-example
:END:
*** Post sub-heading 1
**** Post sub-heading 1.1
***** Post sub-heading 1.1.1
**** Post sub-heading 1.2
**** Post sub-heading 1.3
*** Post sub-heading 2
**** Post sub-heading 2.1
**** Post sub-heading 2.2
***** Post sub-heading 2.2.1
***** Post sub-heading 2.2.2
:PROPERTIES:
:UNNUMBERED: t
:END:
The =UNNUMBERED= property for this subtree is set to =t=. So this
heading will show up as unnumbered in both the post body and the TOC.
***** Post sub-heading 2.2.3
*** Post sub-heading 3
**** Post sub-heading 3.1
** Example text with code blocks
:PROPERTIES:
:CUSTOM_ID: example-text-with-code-blocks
:END:
Here are few variables that you might like to change in the =local.mk=:
- =prefix= :: Org installation directory
  #+begin_src makefile
  prefix = /dir/where/you/want/to/install/org # Default: /usr/share
  #+end_src
  The =.el= files will go to =$(prefix)/emacs/site-lisp/org= by
              default. If you'd like to change that, you can tweak the
              =lispdir= variable.
- =infodir= :: Org Info installation directory. I like to keep the
                   Info file for development version of Org in a separate
                   directory.
  #+begin_src makefile
  infodir = $(prefix)/org/info # Default: $(prefix)/info
  #+end_src
- =ORG_MAKE_DOC= :: Types of Org documentation you'd like to build by
                    default.
  #+begin_src makefile
  # Define below you only need info documentation, the default includes html and pdf
  ORG_MAKE_DOC = info pdf card # html
  #+end_src
- =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.
  #+begin_src makefile
  # 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
  #+end_src

Here's an example of an =emacs-lisp= block:
#+begin_src emacs-lisp
(defvar emacs-version-short (format "%s_%s"
                                    emacs-major-version emacs-minor-version)
  "A variable to store the current emacs versions as <MAJORVER>_<MINORVER>.
So, for emacs version 25.0.50.1, this variable will be 25_0.")
#+end_src

Here's an example of a =python= block ({{{oxhugoissue(314)}}}):
#+begin_src python
import itertools as it
import numpy as np

def permanent(m):
    nr,nc = np.shape(m)
    if nr != nc:
        raise ValueError("Matrix must be square")
    pm = 0
    for p in it.permutations(range(nr)):
        pm += np.product([m[i,p[i]] for i in range(nr)])
   return pm
#+end_src
** Source block with line numbers examples
:PROPERTIES:
:CUSTOM_ID: source-block-with-line-numbers-examples
:END:
#+begin_src org :noweb-ref src-block-n-default-start
,#+begin_src emacs-lisp -n
;; this will export with line number 1 (default)
(message "This is line 2")
,#+end_src
#+end_src

#+begin_src org :noweb-ref src-block-n-custom-start
,#+begin_src emacs-lisp -n 20
;; this will export with line number 20
(message "This is line 21")
,#+end_src
#+end_src

#+begin_src org :noweb-ref src-block-n-default-continue
,#+begin_src emacs-lisp +n
;; This will be listed as line 22
(message "This is line 23")
,#+end_src
#+end_src

#+begin_src org :noweb-ref src-block-n-custom-continue
,#+begin_src emacs-lisp +n 10
;; This will be listed as line 33
(message "This is line 34")
,#+end_src
#+end_src
** Source block with line highlighting examples
:PROPERTIES:
:CUSTOM_ID: source-block-with-line-highlighting-examples
:END:
#+begin_src org :noweb-ref src-block-hl-without-n-just-1-line
,#+begin_src emacs-lisp :hl_lines 2
(message "This is line 1")
(message "This is line 2")
(message "This is line 3")
,#+end_src
#+end_src

#+begin_src org :noweb-ref src-block-hl-without-n
,#+begin_src emacs-lisp :hl_lines 1,3-5
(message "This is line 1")
(message "This is line 2")
(message "This is line 3")
(message "This is line 4")
(message "This is line 5")
(message "This is line 6")
,#+end_src
#+end_src

#+begin_src org :noweb-ref src-block-hl-with-n-not-1
,#+begin_src emacs-lisp -n 7 :hl_lines 1,3-5
(message "This is line 7 in code, but line 1 for highlighting reference")
(message "This is line 8 in code, but line 2 for highlighting reference")
(message "This is line 9 in code, but line 3 for highlighting reference")
(message "This is line 10 in code, but line 4 for highlighting reference")
(message "This is line 11 in code, but line 5 for highlighting reference")
(message "This is line 12 in code, but line 6 for highlighting reference")
,#+end_src
#+end_src

#+begin_src org :noweb-ref src-block-hl-with-n
,#+begin_src emacs-lisp -n :hl_lines 1,3-5
(message "This is line 1")
(message "This is line 2")
(message "This is line 3")
(message "This is line 4")
(message "This is line 5")
(message "This is line 6")
,#+end_src
#+end_src
* Meta
** Search
:PROPERTIES:
:EXPORT_HUGO_SECTION: /
:EXPORT_FILE_NAME: search
:EXPORT_HUGO_LAYOUT: search
:EXPORT_HUGO_MENU: :menu "0.search" :title "Click to Search"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :sitemap '((priority . 0.1))
:EXPORT_HUGO_OUTPUTS: html json
:END:
Results from static site search implemented using /Fusejs/, /jquery/
and /mark.js/. -- [[https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae][Source]]
* Footnotes

[fn:7] English on line 1
の Japanese on line 2

[fn:6] これは
テストです.

[fn:5] See [@thompson2016].

[fn:4] Even if the user has set the =HUGO_CODE_FENCE= value to =t=
(via variable, keyword or subtree property), the Hugo =highlight=
shortcode will be used automatically instead of code fences if either
(i) the user has chosen to either show the line numbers, or (ii) has
chosen to highlight lines of code (See the =ox-hugo= documentation on
{{{doc(source-blocks,Source Blocks)}}}).

[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
