|
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 == 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
#+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.conway.com |
**** Basic styling
***** Uncollapsed borders
#+begin_export html
#+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
#+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
#+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
#+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
#+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
#+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
#+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
#+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
=markup.highlight.codeFences= to =true= (default) 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
=markup.highlight.codeFences= to =true= (default) 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
** Source block annotations :src_block:annotations:
*** Code fence annotation with Goldmark :goldmark:
**** Source blocks with line number annotation (Goldmark) :linenum:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-with-line-numbers
:EXPORT_HUGO_ALIASES: source-block-with-line-numbers-goldmark
:END:
- [[https://orgmode.org/manual/Literal-examples.html][Org reference]]
***** Cases
:PROPERTIES:
:CUSTOM_ID: source-block-line-number-cases
:END:
****** Default new line number start
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
****** Specify new line number start
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
****** Default continued line numbers
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
****** Specify continued line numbers jump
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
***** Specifying ~linenos~ parameter
#+begin_src emacs-lisp :linenos false
(message "This is line 1")
(message "This is line 2")
(message "This is line 3")
#+end_src
#+begin_src emacs-lisp -n 30 :linenos inline
(message "This is line 30")
(message "This is line 31")
(message "This is line 32")
#+end_src
**** Source blocks with highlighting (Goldmark) :highlight:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-with-highlighting
:CUSTOM_ID: source-blocks-with-highlighting
:EXPORT_HUGO_ALIASES: source-block-with-highlighting-goldmark
:EXPORT_HUGO_GOLDMARK: t
:END:
***** Without line numbers
:PROPERTIES:
:CUSTOM_ID: source-blocks-with-highlighting-no-linenums
:END:
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+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
<>
#+end_src
******** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+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 if the =linenos= option is set to =table=
(default).
- 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
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
***** With line numbers
:PROPERTIES:
:CUSTOM_ID: source-blocks-with-highlighting-with-linenums
:END:
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+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
*** Annotate code blocks need =highlight= shortcode in Blackfriday :blackfriday:
:PROPERTIES:
:EXPORT_HUGO_GOLDMARK:
:END:
**** Source blocks with line number annotation (Blackfriday) :linenum:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-with-line-numbers-blackfriday
:END:
- [[https://orgmode.org/manual/Literal-examples.html][Org reference]]
- [[https://gohugo.io/content-management/syntax-highlighting/][Hugo =highlight= shortcode with line numbers]]
***** Cases
****** Default new line number start
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
****** Specify new line number start
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
****** Default continued line numbers
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
****** Specify continued line numbers jump
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
***** Specifying ~linenos~ parameter
#+begin_src emacs-lisp :linenos false
(message "This is line 1")
(message "This is line 2")
(message "This is line 3")
#+end_src
#+begin_src emacs-lisp -n 30 :linenos inline
(message "This is line 30")
(message "This is line 31")
(message "This is line 32")
#+end_src
**** Source blocks with highlighting (Blackfriday) :highlight:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-with-highlighting-blackfriday
:END:
***** Without line numbers
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+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
<>
#+end_src
******** Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
***** With line numbers *not* starting from 1
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+end_src
***** With line numbers
******* Org source
#+begin_src org :noweb yes
<>
#+end_src
******* Output
#+begin_src org :noweb yes :exports results :results output replace :eval yes
<>
#+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:
#+begin_description
Test source blocks inside list.
#+end_description
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
-----
{{{oxhugoissue(645)}}}
1. paragraph -> src block with caption -> paragraph -> src block
#+name: code__foo
#+caption: Foo
#+begin_src emacs-lisp
(message "hey")
#+end_src
sandwiched paragraph
#+begin_src emacs-lisp
(message "hey")
#+end_src
last paragraph
2. paragraph -> src block *without* caption -> paragraph -> src block
#+begin_src emacs-lisp
(message "hey")
#+end_src
sandwiched paragraph
#+begin_src emacs-lisp
(message "hey")
#+end_src
last paragraph
**** 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:src_block:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-indented
:EXPORT_HUGO_GOLDMARK: t
: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)}}}
#+html:
#+attr_html: :class red
#+begin_note
Switched from exporting the ~highlight~ shortcode to exporting the
code fenced blocks with attributes. These code fences are support by
Hugo + Goldmark since v0.60.0.
*Below notes are now outdated and thus grayed out.*
#+end_note
#+html:
#+begin_gray
This is an *upstream* bug in ~hugo~ as of 2018-05-12. The issue 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.
#+end_gray
- 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:
#+begin_description
Test verbatim use of Hugo shortcodes in content.
#+end_description
*** Shortcodes escaped
The =figure= shortcodes in the two Markdown source code blocks below
should *not* be expanded.. they should be visible verbatim.
- src_md[:exports code]{{{< .. >}}} --- [[https://gohugo.io/content-management/shortcodes/#shortcodes-without-markdown][Shortcodes without Markdown]]
- src_md[:exports code]{{{% .. %}}} --- [[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 code fences with line numbering enabled
Here, the =-n= switch is added to the Org source block to enable line
numbering.
#+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
**** Shortcode escaped in Org source blocks
#+begin_src org
,#+macro: relref @@hugo:[@@ $1 @@hugo:]({{< relref "$2" >}})@@
#+end_src
**** Shortcode escaped in Emacs-Lisp source blocks
{{{oxhugoissue(680)}}}
#+begin_src emacs-lisp
;; Follow Hugo links
(defun org-hugo-follow (link)
"Follow Hugo link shortcodes"
(org-link-open-as-file
(string-trim "{{% ref test.org %}}" "{{% ref " "%}}")))
;; New link type for Org-Hugo internal links
(org-link-set-parameters
"hugo"
:complete (lambda ()
(concat "{{% ref */"
(file-name-nondirectory
(read-file-name "File: "))
" %}}"))
:follow #'org-hugo-follow)
#+end_src
*** Shortcodes *not* escaped
The =figure= shortcode in the below example block *should* be
expanded.. you should be seeing a little unicorn below.
#+begin_example
{{< 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).
Below, the same ~figure~ shortcode is called with the ~%~ syntax.
- Note :: If you are using Hugo 0.55.0 or newer, you will just see the
raw HTML from this shortcode (unrendered HTML) because the behavior
of {{% .. %}} shortcodes [[https://gohugo.io/news/0.55.0-relnotes/#shortcodes-revised][changed in Hugo v0.55.0]].
#+begin_example
{{% figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" %}}
#+end_example
-----
*It is necessary to set the Hugo site config variable
=markup.highlight.codeFences= to =true= (default) 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.
#+attr_css: :color blue
#+attr_html: :class blue w-40
#+begin_src goat
┌─────┐ ┌───┐
│Alice│ │Bob│
└──┬──┘ └─┬─┘
│ │
│ Hello Bob! │
│───────────>│
│ │
│Hello Alice!│
│<───────────│
┌──┴──┐ ┌─┴─┐
│Alice│ │Bob│
└─────┘ └───┘
#+end_src
** Coderef :coderef:annotation:example_block:
:PROPERTIES:
:EXPORT_FILE_NAME: coderef
:END:
#+begin_description
Support anchoring the source and example block lines using Org coderef
links.
#+end_description
See [[info:org#Literal Examples]].
In literal examples, Org interprets strings like ~(ref:name)~ as
labels, and use them as targets for special hyperlinks like
~[[(name)]]~ --- i.e., the reference name enclosed in single
parenthesis.
#+begin_quote
Line numbers are always enabled if coderefs are used. The code blocks
are exported as if the user always added the ~-n~ switches to the
source or example block header.
#+end_quote
*** Source block
**** Default line nums with coderef labels
#+begin_src emacs-lisp
(save-excursion (ref:sc)
(goto-char (point-min)) (ref:jump)
#+end_src
In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] jumps to
point-min.
**** Default line nums without coderef labels
#+begin_src emacs-lisp -r
(save-excursion (ref:sc1)
(goto-char (point-min)) (ref:jump1)
#+end_src
In line [[(sc1)]] we remember the current position. [[(jump1)][Line (jump1)]] jumps to
point-min.
**** Custom line nums without coderef labels
#+begin_src emacs-lisp -n 20 -r
(save-excursion (ref:sc2)
(goto-char (point-min)) (ref:jump2)
#+end_src
In line [[(sc2)]] we remember the current position. [[(jump2)][Line (jump2)]] jumps to
point-min.
**** Custom line nums without coderef labels and with highlighting
#+begin_src emacs-lisp -n 20 -r :hl_lines 2
(save-excursion
(goto-char (point-min)) (ref:jump3)
#+end_src
[[(jump3)][Line (jump3)]] jumps to point-min.
**** Reference to lines *before* code block
In line [[(sc4)]] we remember the current position. [[(jump4)][Line (jump4)]] jumps to
point-min.
#+begin_src emacs-lisp -r
(save-excursion (ref:sc4)
(goto-char (point-min)) (ref:jump4)
#+end_src
*** Example block
#+begin_example -n 20 -r :hl_lines 2
(save-excursion
(goto-char (point-min)) (ref:jump5)
#+end_example
[[(jump5)][Line (jump5)]] jumps to point-min.
** Source blocks with langs that need to be replaced in Markdown :lang:syntax_highlighting:
:PROPERTIES:
:EXPORT_FILE_NAME: source-block-replace-langs-in-exported-md
:END:
#+begin_src ipython
(print "hello")
#+end_src
#+begin_src jupyter-python
(print "hello")
#+end_src
* Inline code blocks :inline:code:
:PROPERTIES:
:EXPORT_FILE_NAME: inline-code-blocks
:END:
#+begin_description
Test exporting inline code blocks
#+end_description
[[https://orgmode.org/manual/Structure-of-Code-Blocks.html][Reference]]
** Only results (default)
#+begin_src org
src_emacs-lisp{(message "Hello 1")}
#+end_src
src_emacs-lisp{(message "Hello 1")} {{{results(=Hello 1=)}}}
Above is the same as:
#+begin_src org
src_emacs-lisp[:exports results]{(message "Hello 1")}
#+end_src
src_emacs-lisp[:exports results]{(message "Hello 1")} {{{results(=Hello 1=)}}}
** Only code
#+begin_src org
src_emacs-lisp[:exports code]{(message "Hello 2")}
#+end_src
src_emacs-lisp[:exports code]{(message "Hello 2")} {{{results(=Hello 2=)}}}
** Both code and results
#+begin_src org
src_emacs-lisp[:exports both]{(message "Hello 3")}
#+end_src
src_emacs-lisp[:exports both]{(message "Hello 3")} {{{results(=Hello 3=)}}}
** None!
#+begin_src org
src_emacs-lisp[:exports none]{(message "Hello 4")}
#+end_src
src_emacs-lisp[:exports none]{(message "Hello 4")} {{{results(=Hello 4=)}}}
** Escape Hugo shortcodes
- md :: src_md[:exports code]{{{< some_shortcode "foo" >}}}
- org :: src_org[:exports code]{{{% some_shortcode "foo" %}}}
- go-html-template :: src_go-html-template[:exports code]{{{< some_shortcode "foo" >}}}
** Using custom CSS for inline src blocks
{{{oxhugoissue(638)}}}
CSS used here:
#+begin_src html :noweb-ref inline_src_css
#+end_src
#+begin_export html
#+end_export
{{{oxhugoissue(640)}}} -- Test that straight quotes in inline src
blocks don't get rendered as curved quotes by Hugo/Goldmark's
Typographer.
In Nim, src_nim[:exports code]{echo "hello"} will print
{{{results(/hello/)}}}.
** COMMENT Wrapping inline source block in a list item
As of <2022-03-01 Tue>, below snippet exports incorrectly due to a bug
in Org element parsing in Org mode. The issue was [[https://lists.gnu.org/r/emacs-orgmode/2022-03/msg00008.html][reported on the
mailing list today]].
- abcdefg abcdefg abcdefg abcdefg src_org[:exports code]{[[abc
def][bar]]}.
* 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~= | =key-binding= | |
| | - if =org-hugo-use-code-for-kbd= is non-nil | |
| | - Requires *CSS* to render the == tag as something special. | |
| =+strike-through+= | =~~strike-through~~= | +strike-through+ |
| =_underline_= | =underline= | _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 =C-h f= 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
== tag generation by setting =EXPORT_HUGO_USE_CODE_FOR_KBD=
property to =t=. So =~C-h f~= will show up as =C-h f=.
Example:
- Few of Emacs help keybindings: ~C-h f~, ~C-h v~
- Test auto-protection of angle brackets: ~S-~
*** 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
=C-h f= 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]]
*** Default new line number start
#+begin_example -n
line 1
line 2
#+end_example
An example without ~-n~:
#+begin_example
foo
bar
#+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
*** Specifying ~linenos~ parameter
In the below block, ~:linenos false~ switch was added to the example
block header.
#+begin_example :linenos false
This is line 1
This is line 2
This is line 3
#+end_example
** Example blocks with ATTR_HTML :attr___html:attr___css:
*** Example blocks with ATTR_HTML (Goldmark) :goldmark:
: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.
#+attr_html: :class heavy :title some code block
#+attr_css: :font-weight bold
#+begin_example -n
This is an example
Line 2
Line 3
#+end_example
*** Example blocks with ATTR_HTML (Blackfriday) :blackfriday:
:PROPERTIES:
:EXPORT_FILE_NAME: example-blocks-with-attr-html-blackfriday
:EXPORT_HUGO_GOLDMARK:
: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.
#+attr_html: :class heavy
#+attr_css: :font-weight bold
#+begin_example -n
This is an example
Line 2
Line 3
#+end_example
* 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 with nested maps
:PROPERTIES:
:EXPORT_FILE_NAME: menu-with-nested-maps
:EXPORT_HUGO_MENU: :menu "signalandsystems" :weight 2.0 :parent "chapter 1 advanced problems"
:END:
#+begin_description
Test ~menu~ front-matter with nested maps.
#+end_description
{{{oxhugoissue(325)}}}
** 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:
** ~#+hugo~ keyword :keyword:hugo:
*** 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
*** Hugo keyword
:PROPERTIES:
:EXPORT_FILE_NAME: hugo-keyword
:END:
#+begin_description
Stuff followed the ~#+hugo:~ exports as-is except when it is "more"
#+end_description
As the content following ~#+hugo:~ exports as-is to the Markdown, that
content should be what Hugo can parse (i.e. Markdown, shortcodes,
etc).
This Org snippet:
#+begin_src org
,#+hugo: This `relref` links to [this same page]({{< relref "hugo-keyword" >}}).
#+end_src
renders as below:
#+hugo: This `relref` links to [this same page]({{< relref "hugo-keyword" >}}).
**** Using ~#+hugo:~ for unpaired shortcodes with named arguments
{{{oxhugoissue(624)}}}
#+begin_src org
,#+hugo: {{< myshortcode-named arg1="horizontal" arg2="static/img/legacy/works/land" >}}
#+end_src
renders as below:
#+hugo: {{< myshortcode-named arg1="horizontal" arg2="static/img/legacy/works/land" >}}
** Dealing with underscores
:PROPERTIES:
:EXPORT_FILE_NAME: dealing-with-underscores
:EXPORT_DATE: 2017-07-21
:END:
*** Cases where the underscores should be escaped
_something
foo bar _something foo bar
something_
foo bar something_ foo bar
*** Cases when the underscores should not be escaped
- By itself :: _
- In a verbatim block :: =_=
- In an emoji :: :raised_hands:, :white_check_mark:
- In a citation :: @abc_def
*** Cases where the underscores are removed :noexport:
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 (Goldmark) :italic:links:underscore:goldmark:
:PROPERTIES:
:EXPORT_FILE_NAME: italicize-links-with-underscores-goldmark
:EXPORT_HUGO_ALIASES: italicize-links-with-underscores
:EXPORT_HUGO_GOLDMARK: t
:END:
#+begin_description
Test that links with underscores can be italicized/emboldened/both
without replacing underscores with ~%5f~.
#+end_description
{{{oxhugoissue(308)}}}, {{{oxhugoissue(170)}}}
*** External links
- Italic :: /What is a [[https://en.wikipedia.org/wiki/Two's_complement][two's complement]]?/
- Bold :: *What is a [[https://en.wikipedia.org/wiki/Two's_complement][two's complement]]?*
- Bold + Italic :: /*What is a [[https://en.wikipedia.org/wiki/Two's_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]]?*/
** Italicize links with underscores (Blackfriday) :italic:links:underscore:blackfriday:
:PROPERTIES:
:EXPORT_FILE_NAME: italicize-links-with-underscores-blackfriday
:EXPORT_HUGO_GOLDMARK:
:END:
#+begin_description
Test that links with underscores can be italicized/emboldened/both.
#+end_description
{{{oxhugoissue(170)}}}
- Italic :: /What is a [[https://en.wikipedia.org/wiki/Two's_complement][two's complement]]?/
- Bold :: *What is a [[https://en.wikipedia.org/wiki/Two's_complement][two's complement]]?*
- Bold + Italic :: /*What is a [[https://en.wikipedia.org/wiki/Two's_complement][two's complement]]?*/
** 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 | "" | “” |
| 6 | "". | “”. |
#+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 ==
section.
So the title of this post should read as "ndash and mdash".
** Escaping hashes and exclamations correctly in body :escaping:
: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 not be escaped as it's a solo underscore character. But
the following underscore will be escaped: something_.
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.
** Escaping angle brackets :escaping:angle_brackets:
:PROPERTIES:
:EXPORT_FILE_NAME: escaping-angle-brackets
:END:
#+begin_description
Test the escaping of angle brackets because they are used in HTML tags.
#+end_description
- some <text>
- some < /italic text/ > (spaces are required between the italics
formatting chars and ~<~ / ~>~)
If you really need to put verbatim HTML in Org source, use
~#+begin_export html~ block:
#+begin_export html
<ul>
<li><b>This is in bold</b></li>
<li><i>This is in italics</i></li>
</ul>
#+end_export
This also works if you /desperately need/ to inline HTML within your
Org source: @@html:<b>This is bold</b>@@ .. But why@@html:<span
style="color:red;">‽</span>@@.
** 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 (Bundle container)
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: page-bundle-a
:END:
*** Page Bundle A :leaf_bundle:
: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/.
- [[*Page Bundle B][Link to Leaf Bundle B]]
- [[*Branch Bundle C][Link to Branch Bundle C]]
**** 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 :leaf_bundle:
:PROPERTIES:
:EXPORT_FILE_NAME: index
:EXPORT_HUGO_BUNDLE: page-bundle-b
:END:
Index page of /Page Bundle B/.
- [[*Page Bundle A][Link to Leaf Bundle A]]
- [[*Branch Bundle C][Link to Branch Bundle C]]
[[../files-to-be-copied-to-static/foo/copy-2-of-unicorn-logo.png]]
** Branch Bundle C :branch_bundle:
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: branch-bundle-c
:EXPORT_FILE_NAME: _index
:END:
#+begin_description
Example branch bundle.
#+end_description
- [[*Page Bundle A][Link to Page Bundle A]]
- [[*Page Bundle B][Link to Page Bundle B]]
** 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/main/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 :multi_line:
*** Blackfriday :blackfriday:
:PROPERTIES:
:EXPORT_HUGO_GOLDMARK:
:END:
**** Multi-line footnote (Blackfriday)
:PROPERTIES:
:EXPORT_FILE_NAME: multi-line-footnote-blackfriday
:END:
This is some text[fn:3].
*** Goldmark :goldmark:
:PROPERTIES:
:EXPORT_HUGO_GOLDMARK: t
:END:
**** Multi-line footnote (Goldmark)
:PROPERTIES:
:EXPORT_FILE_NAME: multi-line-footnote-goldmark
:EXPORT_HUGO_ALIASES: multi-line-footnote
:END:
This is some text[fn:3].
**** Footnote with source block :src_block:
:PROPERTIES:
:EXPORT_FILE_NAME: footnote-with-src-block
:END:
#+begin_description
Exporting footnote with source block
#+end_description
{{{oxhugoissue(433)}}}
Testing code in a footnote with a ~#+begin_src~ directive.[fn:8]
** 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 = =.
a a a a a a a a a a a a a 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 = =,
*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 = =.
a a a a a a a a a a a a a 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 = =,
*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:a__b__c:
: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
:EXPORT_OPTIONS: tags:nil
:END:
#+begin_description
Disable exporting of sub-heading tags by setting export option
~tags:nil~.
#+end_description
*** 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 attributes :attributes:
:PROPERTIES:
:EXPORT_FILE_NAME: links-with-attributes
:EXPORT_HUGO_ALIASES: links-with-target-attribute
:END:
#+begin_description
Testing links with different HTML attributes.
#+end_description
*** Links with ~target~ attribute
#+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.
*** Links with ~title~ and ~style~ attributes
#+attr_html: :title The Org mode homepage :style color:red;
[[https://orgmode.org]]
** 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]].*
**** Using Org targets as verbatim anchors
paragraph 1
<<.paragraph-2>>
paragraph 2
[[.paragraph-2][Link to paragraph 2]]
*** 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. A reference
to a radio target something something that has spaces in it.
#+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>>>.
Here I talk about <<<something something>>>.
** 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 headings and
links to targets will be resolved to the containing file.
- [[file:issues/issue-556.org::#heading-xyz][Link to CUSTOM_ID]]
- [[file:issues/issue-556.org::* Heading 3][Link to a heading]]
- Links to Org Targets: [[file:issues/issue-556.org::paragraph-2][here]] and [[file:issues/issue-556.org::.paragraph-3][here]]
*** 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 heading within the same post]]
- Links to target links within the same post like [[internal target link][this]].
*** 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 headings, 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 heading: [[*Link destination]]
- Link to a subtree with custom Hugo slug: [[*Slug Front-matter]]
**** 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 heading]]
- [[*Slug Front-matter][Link to a subtree with custom Hugo slug]]
*** Internal target
:PROPERTIES:
:CUSTOM_ID: internal-target
:ID: 8e65ff86-3f9a-48ef-9b43-751a2e8a9372
:END:
<<internal target link>>
** 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]]
** Links to Info manual nodes :info:
:PROPERTIES:
:EXPORT_FILE_NAME: links-to-info-manual-nodes
:END:
#+begin_description
Test links to Info manual nodes.
#+end_description
- Link to an Org Info manual node: [[info:org#Search Options]]
- Links to Top nodes of manuals: [[info:emacs#Top]] | [[info:org#Top]]
- Link to an Emacs Info manual node: [[info:emacs#Point]] (same link but
with a custom description: [[info:emacs#Point][🛈 Emacs: Point]])
- Link to an Emacs Lisp Info manual node: [[info:elisp#Lambda Expressions]]
- Link to a GNU software (~tar~) Info manual node: [[info:tar#Old Options]]
* Equations :equations:
** MathJax :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}
**** Backslashes within a LaTeX equation
{{{oxhugoissue(458)}}}
Double backslashes (~\\~) should be escaped:
\[\sum_{\substack{0<i<m\\0<j<n}}\]
A backslash before any ASCII punctuation character should be escaped,
for example, ~\,~, ~\;~, ~\:~, ~\!~ are used to control the width of
spacing:
\[ab\]
\[a\ b\]
\[a\,b\]
\[a\;b\]
\[a\:b\]
\[a\!b\]
** Equations exported to SVG (dvisvgm) :dvisvgm:dont_export_during_make_test:
:PROPERTIES:
:EXPORT_FILE_NAME: equations-exported-to-svg
:EXPORT_OPTIONS: tex:dvisvgm
:END:
#+begin_description
Exporting {{{latex}}} equations as SVG images.
#+end_description
{{{oxhugoissue(327)}}}
Example of an inline equation: \[ a + b \]
Testing ~$ .. $~ inline equations from {{{oxhugoissue(611)}}} : Let us
try an inline formula like $p \to q$. Does this work? $r \to s$
Example of a block equation:
\begin{equation}
C = W\log_{2} (1+\mathrm{SNR})
\end{equation}
#+begin_note
Referencing to equation labels does not work when {{{latex}}}
equations are exported as images.
#+end_note
*** tikz
{{{oxhugoissue(565)}}}
#+latex_header: \usepackage{tikz}
#+latex_header: \usepackage{pgfplots}
\begin{equation*}\begin{tikzpicture}
\draw[gray, thick] (-1,1) -- (1,-1);
\end{tikzpicture}\end{equation*}
** Equations exported to PNG (dvipng) :dont_export_during_make_test:dvipng:
:PROPERTIES:
:EXPORT_FILE_NAME: equations-exported-to-png
:EXPORT_OPTIONS: tex:dvipng
:END:
#+begin_description
Exporting {{{latex}}} equations as PNG images.
#+end_description
{{{oxhugoissue(473)}}}
Example of an inline equation: \[ a + b \]
Example of a block equation:
\begin{equation}
C = W\log_{2} (1+\mathrm{SNR})
\end{equation}
#+begin_note
Referencing to equation labels does not work when {{{latex}}}
equations are exported as images.
#+end_note
* 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:
#+begin_description
Test paragraphs inside various list types.
#+end_description
- 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.
- foo1 :: Descriptive list item.
Paragraph 1 in the desc list item.
Paragraph 2 in the desc list item.
- foo2 :: Descriptive list item.
Paragraph 1 in the desc list item.
Paragraph 2 in the desc list item.
** 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.
2. This will be 2.
10. [@10] This will be 10!
11. This will be 11.
17. [@17] This will be 17!
18. This will be 18.
123. [@123] This will be 123!
124. This will be 124.
1. This will be 1 again.
2. This will be 2.
Another example:
1. This will be 1.
3. [@3] This will be 3!
7. [@7] This will be 7!
100. [@100] This will be 100!
Ordered list numbers larger then 99:
100. [@100] This will be 100!
101. This will be 101.
102. This will be 102.
999999997. [@999999997] This will be 999999997!
999999998. This will be 999999998.
999999999. This will be 999999999. CommonMark 0.30 [[https://spec.commonmark.org/0.30/#ordered-list-marker][allows]] an ordered
list marker to be at max 9 digits long.
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
: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_export html
<style>
.verse {
color: red;
}
</style>
#+end_export
/Below verse should render in red./
#+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 = = in HTML.
#+begin_verse
> Text indented by 4 tab characters
#+end_verse
*** Corner cases
#+begin_src org -n 0
,#+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
#+end_src
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_src org -n 0
,#+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
#+end_src
#+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 Elements
**** 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
**** Inline HTML5 elements
Unmarked.
#+begin_mark
/Some/ *marked* text --- 2.5.
#+end_mark
Unmarked again.
#+header: :trim-pre nil :trim-post nil
#+begin_mark
Page Bundles of =page= [[https://gohugo.io/templates/section-templates/#page-kinds][/Kind/]] are always /leaf bundles/.. and vice versa.
#+end_mark
Here's an inline HTML element ~<cite>~ inside a Quote block:
#+begin_quote
He puts his claw against the divider. "Fist my bump."
#+begin_cite
Andy Weir, Project Hail Mary
#+end_cite
#+end_quote
#+attr_html: :max 100 :value 70
#+begin_progress
70%
#+end_progress
*** 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
#+html: <style>details summary { color: green; }</style>
#+html: <style>details .details { color: blue; }</style>
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
*** 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
** TikZJax :tikzjax:
:PROPERTIES:
:EXPORT_FILE_NAME: tikzjax
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :tikzjax true
:END:
#+begin_description
TikZJax example
#+end_description
{{{oxhugoissue(390)}}}
<<circle>>
#+attr_html: :caption Picture of a circle
#+begin_tikzjax
\draw (0,0) circle (1in);
#+end_tikzjax
Here's a link to the [[circle][Circle]].
** Whitespace trimming :whitespace:trimming:
*** Whitespace trimming around special blocks
:PROPERTIES:
:EXPORT_FILE_NAME: ws-trimming-around-special-blocks
:EXPORT_DESCRIPTION: Whitespace trimming using ~#+header: :trim-pre t :trim-post t~ before special blocks.
:END:
By default (in ~org-hugo-special-block-type-properties~), the "mark"
special block type has ~:trim-pre~ and ~:trim-post~ both set to ~t~,
because typically the ~<mark>~ is used to highlight words and phrases
mid-sentence and we wouldn't want to introduce a paragraph break
before or after a ~<mark>~ element.
**** Whitespace trimmed before and after the ~mark~ special block (default)
Below Org block:
#+begin_src org
line 1
,#+begin_mark
abc def
,#+end_mark
line 2
#+end_src
exports and renders as:
line 1
#+begin_mark
abc def
#+end_mark
line 2
**** Whitespace trimmed only before the ~mark~ special block
Below Org block:
#+begin_src org
line 1
,#+header: :trim-post nil
,#+begin_mark
abc def
,#+end_mark
line 2
#+end_src
exports and renders as:
line 1
#+header: :trim-post nil
#+begin_mark
abc def
#+end_mark
line 2
**** Whitespace trimmed only after the ~mark~ special block
Below Org block:
#+begin_src org
line 1
,#+header: :trim-pre nil
,#+begin_mark
abc def
,#+end_mark
line 2
#+end_src
exports and renders as:
line 1
#+header: :trim-pre nil
#+begin_mark
abc def
#+end_mark
line 2
**** No trimming
Below Org block:
#+begin_src org
line 1
,#+header: :trim-pre nil :trim-post nil
,#+begin_mark
abc def
,#+end_mark
line 2
#+end_src
exports and renders as:
line 1
#+header: :trim-pre nil :trim-post nil
#+begin_mark
abc def
#+end_mark
line 2
**** Use ~<span>~ tag if trimming detected
Below Org block:
#+begin_src org
line 1
,#+begin_foo
abc def
,#+end_foo
line 2
#+end_src
exports with ~<div>~ tags by default:
#+begin_src html -n
line 1
<div class="foo">
abc def
</div>
line 2
#+end_src
and renders as:
line 1
#+begin_foo
abc def
#+end_foo
line 2
But if any of the trimming options are set in the header, it switches
to using the ~<span>~ tag. So the below Org block:
#+begin_src org
line 1
,#+header: :trim-pre t :trim-post t
,#+begin_foo
abc def
,#+end_foo
line 2
#+end_src
will export to:
#+begin_src html -n
line 1 <span class="foo">abc def</span> line 2
#+end_src
and render as:
line 1
#+header: :trim-pre t :trim-post t
#+begin_foo
abc def
#+end_foo
line 2
*** Whitespace trimming around special blocks (corner cases) :corner_cases:
:PROPERTIES:
:EXPORT_FILE_NAME: ws-trimming-around-special-blocks-corner-cases
:EXPORT_HUGO_PAIRED_SHORTCODES: %inline
:END:
#+begin_description
Corner cases for testing the whitespace trimming around the special
blocks.
#+end_description
**** Whitespace trimming inside quote blocks
#+begin_quote
line 1
#+begin_mark
marked text
#+end_mark
line 2
line 4 (line 3, above, is blank, but inside the quote block)
#+end_quote
- Special block in a quote block in a list
#+begin_quote
line 1
#+begin_mark
marked text
#+end_mark
line 2
line 4 (line 3, above, is blank, but inside the quote block)
#+end_quote
**** Whitespace trimming before list elements
something
#+begin_mark
marked text
#+end_mark
- list item 1
- list item 2
**** Whitespace trimming before headings
something
#+begin_mark
marked text
#+end_mark
***** Next heading
**** Whitespace trimming before and after code blocks
something
#+begin_mark
marked text
#+end_mark
#+begin_example
code line
#+end_example
#+begin_mark
marked text
#+end_mark
something
~inline code 1~
#+begin_mark
marked text
#+end_mark
~inline code 2~
something
**** Whitespace trimming with ~:trim-pre~ set immediately after a heading
#+begin_mark
marked text
#+end_mark
**** ~>~ character before a special block with ~:trim_pre~ set
#+begin_export html
<style>
.red {
color: red;
}
</style>
#+end_export
#+attr_html: :class red
#+begin_mark
This marked text's foreground is red.
#+end_mark
**** Hugo shortcode in a definition list with pre/post trimming
The content in the ~inline~ shortcode (created for this test site)
should render /inline/ and not create a parapraph break at the end of
it.
- defn1 ::
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque et
quam metus. Etiam in iaculis mi, sit amet pretium magna. Donec ut
dui mi. Maecenas pharetra sapien nunc, ut mollis enim aliquam
quis.
#+header: :trim-pre t :trim-post t
#+begin_inline
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque et
quam metus. Etiam in iaculis mi, sit amet pretium magna. Donec ut
dui mi. Maecenas pharetra sapien nunc, ut mollis enim aliquam
quis.
#+end_inline
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque et
quam metus. Etiam in iaculis mi, sit amet pretium magna. Donec ut
dui mi. Maecenas pharetra sapien nunc, ut mollis enim aliquam
quis.
- defn2 ::
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque et
quam metus. Etiam in iaculis mi, sit amet pretium magna. Donec ut
dui mi. Maecenas pharetra sapien nunc, ut mollis enim aliquam
quis.
**** Last element of a post
#+begin_mark
No "post" trim markers should be inserted after this block as it's the
last element of this post.
#+end_mark
* 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 ways 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:
#+begin_description
Tests for paired shortcodes with no arguments.
#+end_description
Test case for feature requested in {{{oxhugoissue(119)}}}.
**** Paired markdown shortcode
#+begin_src org
,#+begin_mdshortcode
Content *with* /emphasis/ characters is rendered.
,#+end_mdshortcode
#+end_src
Above will export as:
#+begin_src md
{{% mdshortcode %}}
Content *with* /emphasis/ characters is rendered.
{{% /mdshortcode %}}
#+end_src
and render as:
#+begin_mdshortcode
Content *with* /emphasis/ characters is rendered.
#+end_mdshortcode
**** Paired non-markdown (default) shortcode
Markdown is !! NOT !! rendered in non-markdown shortcodes.
#+begin_src org
,#+begin_myshortcode
The Markdown /emphasis/ characters are !! NOT !! rendered.
So a blank line before this sentence in the Markdown source will
not result in a new paragraph in HTML.
,#+end_myshortcode
#+end_src
Above will export as:
#+begin_src md
{{< myshortcode >}}
The Markdown /emphasis/ characters are !! NOT !! rendered.
So a blank line before this sentence in the Markdown source will
not result in a new paragraph in HTML.
{{< /myshortcode >}}
#+end_src
and render as:
#+begin_myshortcode
The Markdown /emphasis/ characters are !! NOT !! rendered.
So a blank line before this sentence in the Markdown source will
not result in a new paragraph in HTML.
#+end_myshortcode
**** 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 katex
:END:
#+begin_description
Tests for paired shortcodes with positional arguments.
#+end_description
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.
#+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.
#+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
The Markdown /emphasis/ characters are !! NOT !! rendered.
#+end_myshortcode-pos
{{{oxhugoissue(377)}}}
#+attr_shortcode: display
#+begin_katex
E = -J \sum\_{i=1}^N s\_i s\_{i+1}
#+end_katex
*** 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:
#+begin_description
Tests for paired shortcodes with named arguments.
#+end_description
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.
#+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
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
* 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:
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-date-from-logbook
:LOG_INTO_DRAWER: t
:LOGGING: DONE(!)
:EXPORT_OPTIONS: d:t
:END:
:LOGBOOK:
- State "DONE" from "TEST__TODO" [2022-01-11 Tue 11:22]
- 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:
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-lastmod-from-logbook
:LOG_INTO_DRAWER: t
:LOGGING: DONE(!)
:EXPORT_OPTIONS: d:t
:EXPORT_HUGO_AUTO_SET_LASTMOD: 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~.
The ~lastmod~ field parsed from LOGBOOK transitions will have the
highest precedence. So it will *not be auto-set* even if the
~:EXPORT_HUGO_AUTO_SET_LASTMOD: t~ property is set.
** 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]].
** 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
*** Post with ~#+toc: headlines 1~ but no headings
:PROPERTIES:
:EXPORT_FILE_NAME: post-with-toc-headlines-but-no-headings
:END:
#+begin_description
Test the use of ~#+toc: headlines 1~ in a post with no headings.
#+end_description
{{{oxhugoissue(679)}}}
#+toc: headlines 1
*** 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 headings only up to level-N relative to the heading 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
* Citations :citations:
** Org Cite :org_cite:
*** Org Cite Basic Example
:PROPERTIES:
:EXPORT_FILE_NAME: org-cite-basic-example
:EXPORT_DESCRIPTION: Basic example of using [cite:@xyz] citation.
:END:
*Org 9.5* is needed for this as that version introduced
#+begin_mark
the new *oc.el* Org Cite library
#+end_mark
.
**** Specify Bibligraphy files
Org Cite (~oc.el~) requires the bibliography files to be specified
using one or more ~#+bibliography: <file.bib>~ keywords or using the
~org-cite-global-bibliography~ variable.
Example: ~#+bibliography: orgcite.bib~
#+begin_note
~:EXPORT_BIBLIOGRAPHY:~ in subtree property drawers will *not* work
with Org Cite!
#+end_note
**** Citation Syntax
Below Org snippet:
#+begin_src org
[cite:@OrgCitations]
#+end_src
exports to:
[cite:@OrgCitations]
See [[https://blog.tecosaur.com/tmio/2021-07-31-citations.html][the /TMIO/ July 2021 blog post]] for more information on the ~cite:~
syntax.
**** Printing Bibliography
Below Org snippet:
#+begin_src org
,#+print_bibliography:
#+end_src
exports to:
#+print_bibliography:
** Pandoc Citations :pandoc:
:PROPERTIES:
:EXPORT_HUGO_PANDOC_CITATIONS: t
:EXPORT_BIBLIOGRAPHY: cite/bib/bib1.bib, cite/bib/bib2.bib, cite/bib/bib3.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 shortcodes
#+begin_mdshortcode
Text containing *Markdown*
#+end_mdshortcode
Some text.
#+begin_myshortcode
Text not containing *Markdown*
#+end_myshortcode
This link will generate a ~relref~ shortcode: Here's a link to an
arbitrarily picked post: [[*Citation Linking][Citation Linking]].
**** 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
**** Citation key with underscore
Ox-hugo manual (@ox_hugo_man)
*** 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 headings 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 headings (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 headings :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.
** Preserve Breaks :preserve_breaks:
:PROPERTIES:
:EXPORT_FILE_NAME: preserve-breaks
:EXPORT_OPTIONS: \n:t
:END:
abc
def
ghi
** Smart Quotes :smart_quotes:
*** Smart Quotes Test
:PROPERTIES:
:CUSTOM_ID: smart-quotes-test
:END:
**** Single quotes
- Single quotes surrounded by spaces: 'abc'
- Second single quote followed by a period: 'abc'.
- Second single quote followed by a comma: 'abc',
- Brackets inside single quotes: '(abc)', '[abc]', '{abc}', 'xyz
(abc)', 'xyz [abc]', 'xyz {abc}', '(abc) xyz', '[abc] xyz', '{abc}
xyz'
- Brackets inside single quotes (now with periods instead of commas):
'(abc)'. '[abc]'. '{abc}'. 'xyz (abc)'. 'xyz [abc]'. 'xyz
{abc}'. '(abc) xyz'. '[abc] xyz'. '{abc} xyz'
- Single quotes in contractions: it's, I'll, I've, can't
**** Double quotes
- Double quotes surrounded by spaces: "abc"
- Second double quote followed by a period: "abc".
- Second double quote followed by a comma: "abc",
- Brackets inside double quotes: "(abc)", "[abc]", "{abc}", "xyz
(abc)", "xyz [abc]", "xyz {abc}", "(abc) xyz", "[abc] xyz", "{abc}
xyz"
- Brackets inside double quotes (now with periods instead of commas):
"(abc)". "[abc]". "{abc}". "xyz (abc)". "xyz [abc]". "xyz
{abc}". "(abc) xyz". "[abc] xyz". "{abc} xyz"
*** Smart Quotes Enabled :enable:
:PROPERTIES:
:EXPORT_FILE_NAME: smart-quotes-enabled
:EXPORT_OPTIONS: ':t
:END:
#+begin_description
Org mode smart quotes processing enabled
#+end_description
#+include: "./all-posts.org::#smart-quotes-test" :only-contents t
*** Smart Quotes Disabled :disable:
:PROPERTIES:
:EXPORT_FILE_NAME: smart-quotes-disabled
:EXPORT_OPTIONS: ':nil
:END:
#+begin_description
Org mode smart quotes processing disabled
#+end_description
#+include: "./all-posts.org::#smart-quotes-test" :only-contents t
* 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_description
Testing ~#+begin_export hugo~ .. ~#+end_export~ blocks.
#+end_description
#+begin_export hugo
This will get exported **only for** Hugo exports, `verbatim`.
#+end_export
**** Using /export hugo/ block for unpaired shortcodes with named arguments
{{{oxhugoissue(624)}}}
Below:
#+begin_src org
,#+begin_export hugo
{{< myshortcode-named
arg1="horizontal"
arg2="static/img/legacy/works/land"
>}}
,#+end_export
#+end_src
renders as:
#+begin_export hugo
{{< myshortcode-named
arg1="horizontal"
arg2="static/img/legacy/works/land"
>}}
#+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
** LOGBOOK Notes :notes:logbook:
:PROPERTIES:
:LOG_INTO_DRAWER: t
:LOGGING: TODO(!) DRAFT(!) DONE(!)
:EXPORT_OPTIONS: d:t
:EXPORT_HUGO_LAYOUT: alternate-single
:END:
*** DONE Parsing notes from LOGBOOK
:PROPERTIES:
:EXPORT_FILE_NAME: parsing-notes-from-logbook
:END:
:LOGBOOK:
- Note taken on [2022-05-12 Thu 08:13] \\
Another update to the post. This update timestamp should update the
~lastmod~.
- State "DONE" from "TEST__TODO" <2022-05-10 Tue 08:13>
- State "TODO" from "DRAFT" <2022-05-08 Sun 06:13>
- State "DRAFT" from "DONE" <2022-05-06 Fri 04:12>
- Note taken on [2022-05-04 Wed 13:15] \\
This new note added last should be the first element of the
~[[logbook.notes]]~ TOML table array.
- Note taken on [2022-04-08 Fri 14:53] \\
This note addition prompt shows up on typing the ~C-c C-z~ binding.
See [[info:org#Drawers]].
- Note taken on [2018-09-06 Thu 11:45] \\
Another note *bold* /italics/.
- Note taken on [2018-09-06 Thu 11:37] \\
A note ~mono~.
- State "DONE" from "DRAFT" [2018-09-06 Thu 11:25]
- State "DRAFT" from "TODO" [2018-09-04 Tue 11:25]
- State "TODO" from [2018-09-01 Sat 11:25]
:END:
#+begin_description
Parse notes from LOGBOOK into a TOML table (YAML map?) of
~logbook.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 only the notes to an array of TOML tables with key
~logbook.<..>.notes~. The notes are ordered starting from the newest
note first in the TOML table array to the oldest note at the last.
- Note :: The state change notes are intentionally put in this test
LOGBOOK, because we want to ensure that they don't seep into the
~logbook.<..>.notes~ front-matter.
*** LOGBOOK Notes in nested headings
:PROPERTIES:
:EXPORT_FILE_NAME: logbook-notes-in-nested-headings
:END:
:LOGBOOK:
- Note taken on [2022-05-11 Wed 12:17] \\
Note in the top-heading LOGBOOK drawer
:END:
#+begin_description
Parse notes from LOGBOOK drawers in top-level and nested headings.
#+end_description
**** Sub-heading
:LOGBOOK:
- Note taken on [2022-05-11 Wed 12:18] \\
LOGBOOK note in a sub-heading
:END:
**** Sub heading *with* /markup/
:LOGBOOK:
- Note taken on [2022-05-11 Wed 17:12] \\
Another note in a different sub heading.
:END:
Some text in body between two ~:LOGBOOK:~ drawers.
:LOGBOOK:
- Note taken on [2022-05-12 Thu 13:44] \\
Testing a pathogenic case where the user has forcefully inserted a
~:LOGBOOK:~ drawer in the middle of subtree content.
:END:
Text after the second ~:LOGBOOK:~ drawer.
*** DONE Post marked as DONE with LOGBOOK Notes in nested headings :lastmod:
:PROPERTIES:
:EXPORT_FILE_NAME: logbook-done-post-with-notes-in-sub-headings
:END:
:LOGBOOK:
- State "DONE" from "DRAFT" <2022-05-01 Sun 08:49>
- State "DRAFT" from "TODO" <2022-04-17 Sun 08:49>
- State "TODO" from <2022-04-01 Fri 08:48>
:END:
#+begin_description
Parse notes from LOGBOOK drawers in top-level and nested headings.
#+end_description
The ~lastmod~ field is not set for this post (even if it has a note
with timestamp) because this post is not marked as DONE.
**** Sub-heading
:LOGBOOK:
- Note taken on [2022-05-12 Thu 08:49] \\
This LOGBOOK note was added in a sub-heading *after* the post was
marked DONE, but this note's timestamp should not affect the post's
~lastmod~ field (because this is not the toplevel LOGBOOK drawer).
:END:
*** DONE Parse lastmod from LOGBOOK Notes with no recorded state changes :lastmod:
CLOSED: <2022-05-10 Tue>
:PROPERTIES:
:EXPORT_FILE_NAME: logbook-lastmod-from-notes
:END:
:LOGBOOK:
- Note taken on [2022-05-12 Thu 10:56] \\
Some note.
:END:
#+begin_description
Parse ~lastmod~ from toplevel LOGBOOK notes even if the drawer didn't
record any state changes.
#+end_description
** 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
** _build Front-matter Bundle :page_bundles:___build:
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: build-front-matter
:END:
*** _build Front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:END:
{{{oxhugoissue(358)}}} | [[https://gohugo.io/content-management/build-options/][~_build~ page params]]
#+hugo: {{< getpage "do-not-list" >}}
#+hugo: {{< getpage "do-not-render" >}}
#+hugo: {{< getpage "do-not-render-or-list" >}}
*** _build: Don't list this page :dont_list:
:PROPERTIES:
:EXPORT_FILE_NAME: do-not-list
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :_build '((list . never))
:END:
#+begin_description
Build this page but don't list it in /list/ pages.
#+end_description
[[https://gohugo.io/content-management/build-options/#list][~_build.list~ option]]
*This is the "do not list" page.*
See the [[../][parent]] list page -- This page is found using the ~.GetPage~
method there, but it won't be listed there under "Posts in
‘posts/build-front-matter/’".
*** _build: Don't render this page :dont_render:
:PROPERTIES:
:EXPORT_FILE_NAME: do-not-render
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :_build '((render . never))
:END:
#+begin_description
Do not render this page, but.. still list it.
#+end_description
[[https://gohugo.io/content-management/build-options/#render][~_build.render~ option]]
*This is the "do not render" page.*
See the [[../][parent]] list page -- This page is not rendered, but its content
and metadata can be found using the ~site.GetPage~ method.
#+header: :trim-pre nil
#+begin_mark
This page is listed on that parent list page, but the link won't lead
to this page as.. it did not get rendered. That link will point to
that page itself because with ~render~ set to ~false~ or ~"never"~,
the ~.Permalink~ and ~.RelPermalink~ get set to ~""~.
#+end_mark
*** _build: Don't render or list this page :dont_render:dont_list:headless:
:PROPERTIES:
:EXPORT_FILE_NAME: do-not-render-or-list
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :_build '((render . false) (list . false))
:END:
#+begin_description
Do not render or list this page.
#+end_description
*This is the "do not render or list" page.*
See the [[../][parent]] list page -- This page is not rendered, but its content
and metadata can be found using the ~site.GetPage~ method.
Setting both ~render~ and ~list~ to ~false~ or ~"never"~ makes this
page behave like a *headless* page bundle -- [[https://github.com/gohugoio/hugo/issues/6412#issuecomment-573446730][ref]].
** Front-matter mixed bag :blackfriday_deprecated:
:PROPERTIES:
:EXPORT_FILE_NAME: front-matter-mixed-bag
:EXPORT_HUGO_BLACKFRIDAY: :extensions hardLineBreak
:END:
With ~org-hugo-goldmark~ non-nil, ~:EXPORT_HUGO_BLACKFRIDAY:
:extensions hardLineBreak~ property of this post will *not* get
exported to the front-matter.
* 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/date-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/date-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)}}}
** Issue 470 -- Fill region on inlined SVG files :svg:
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: 470
:EXPORT_FILE_NAME: index
:END:
#+begin_description
Test to check inlining + fill region of SVG from Issue 470
#+end_description
{{{oxhugoissue(470)}}}
This test shows that it's OK to do fill-region on inlined SVG. In the
referenced issue, the issue author was inlining an SVG file containing
the ~DOCTYPE~ tag and that was causing the problem:
[[https://github.com/kaushalmodi/ox-hugo/issues/470#issuecomment-980385275][https://user-images.githubusercontent.com/3578197/143625834-4548e998-0d45-4c9f-85bb-3d56456d3200.png]]
With the ~DOCTYPE~ tag removed, the browser doesn't throw any error
(below is the SVG from that issue.. seems like it's just blank. But
you will be able to see when you view this page's source).
#+caption: SVG from Issue 470
#+attr_html: :inlined t
[[file:images/svg-from-issue-470.svg]]
* 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.
-----
#+toc: headlines 2
神经网络相关基本知识笔记
*** 神经网络表示
**** 神经元模型
神经网络从大脑的工作原理得到启发，可用于解决通用的学习问题。神经网络的
基本组成单元是 *神经元(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 headings :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*.
Summary can also contain markup (like *bold*, /italics/, etc.).
** 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 - Heading 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:8]
#+begin_src elisp
(emacs-version)
(org-version)
#+end_src
[fn:7] English on line 1
の Japanese on line 2
[fn:6] これは
テストです.
[fn:5] See [@thompson2016].
[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