Skip to content

Commit

Permalink
Add screenshot showing the one-Org-file-per-post flow too
Browse files Browse the repository at this point in the history
  • Loading branch information
@kaushalmodi
kaushalmodi committed Sep 11, 2017
1 parent e9aa837 commit 8eae652
Show file tree
Hide file tree
Showing 11 changed files with 252 additions and 73 deletions.
67 changes: 42 additions & 25 deletions README.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
#+AUTHOR: Kaushal Modi
=ox-hugo= is an Org exporter backend that exports Org to
[[https://gohugo.io/][Hugo]]-compatible Markdown ([[https://github.com/russross/blackfriday][Blackfriday]]). That also includes the
generation of front matter (in TOML or YAML format) for Hugo
generation of front-matter (in TOML or YAML format) for Hugo
posts.

Here is the blogging flow when using this package:
Expand All @@ -21,12 +21,28 @@ This project consists of =ox-blackfriday.el= too. It is a derivation
of [[https://github.com/larstvei/ox-gfm][=ox-gfm=]] with support added for Blackfriday Markdown tables and
many other tweaks. =ox-hugo= backend extends from this.

Before you read further, you can see below the outcome of an =ox-hugo=
export (Org on the left; exported Markdown with Hugo front-matter on
the right).
Before you read further, you can see below how =ox-hugo= translates
Org to Markdown (Org on the left; exported Markdown with Hugo
front-matter on the right).

[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/org-md.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/org-md.png]]
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content-org/screenshot-example.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content/writing-hugo-blog-in-org.md][Markdown]]
*When writing posts as Org subtrees --*
[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-subtree.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-subtree.png]]
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content-org/screenshot-subtree-export-example.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content/writing-hugo-blog-in-org-subtree-export.md][Markdown]]

*When writing each post as a separate Org file --*
[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-file.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-file.png]]
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content-org/writing-hugo-blog-in-org-file-export.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content/writing-hugo-blog-in-org-file-export.md][Markdown]]

The preferred way to organize the posts is as Org subtrees (also the
main reason to write this package, as nothing like that was out there)
as it makes the meta-data management for Hugo front-matter pretty
effortless.

If you are a /one Org-file per post/ type of a person, that flow works
too! Just note that in this flow many of those =#+HUGO_= properties
need to be managed manually.. just as one would manage the front-matter
in Markdown files --- See the Org versions in the above screenshots for
comparison.
* Why =ox-hugo=?
Using Org just as a markup like Markdown is a miniscule part of its
complete feature-set. Org also allows stuff like:
Expand All @@ -39,7 +55,7 @@ complete feature-set. Org also allows stuff like:
- ..

Using Org for content writing allows using in-built Org features to
translate to Hugo front matter:
translate to Hugo front-matter:

- Org uses an outline structure and can inherit meta data (tags and
properties) from one subtree to children subtrees.
Expand Down Expand Up @@ -158,8 +174,25 @@ exported Markdown files.
directory. You can name it anything, but I prefer to name it
=content-org= ([[https://github.com/kaushalmodi/ox-hugo/tree/master/example-site][Example 1 -- =ox-hugo= example site]], [[https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io][Example 2 -- My
blog]]).
5. Create an Org file in there and follow the *Usage* section to
export it.
5. Create an Org file in there and follow the *Usage* section in the
[[https://github.com/kaushalmodi/ox-hugo#usage][README]] or [[https://github.com/kaushalmodi/ox-hugo/wiki/Usage][Wiki]] to export it.
* Translation of Org meta-data to Hugo front-matter
When organizing the posts as Org *subtrees*, many Hugo front-matter
variables get set implicitly using the meta-data parsed from the posts
in Org.
|----------------------------------+------------------------------------+---------------------------------------------------------------------|
| Hugo front-matter (TOML) | Org | Org description |
|----------------------------------+------------------------------------+---------------------------------------------------------------------|
| =title = "foo"​= | =* foo= | Subtree heading (needs to have the =EXPORT_FILE_NAME= property set) |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property (or =#+DATE:=) |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | Heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Heading set to =TODO= (or =DRAFT=) |
| =draft = false= | =* foo= | Heading *not* set to =TODO= (or =DRAFT=) |
| =weight = 123= | =:EXPORT_HUGO_WEIGHT: auto= | When set to =auto=, weight is auto-calculated. |
| =weight = 123= (in =[menu.foo]=) | =:EXPORT_HUGO_MENU: :menu foo= | Menu weight is auto-calculated unless specified. |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property (or =#+HUGO_AUTO_SET_LASTMODE: t=) |
|----------------------------------+------------------------------------+---------------------------------------------------------------------|
* Formatting
Below table shows the translation of Org markup to Markdown markup in
the exported =.md= files.
Expand All @@ -186,22 +219,6 @@ heading and how it exports to Markdown in [[https://raw.githubusercontent.com/ka
/Org/ column in the table above, it is a bug with GitHub's Org
renderer.. just see those as *single* equal signs on each side of
/monospace/ instead.)
* Translation of Org meta-data to Hugo front matter
Many Hugo front matter variables get set implicitly using the
meta-data parsed from the posts in Org.
|----------------------------------+------------------------------------+-----------------------------------------------------|
| Hugo front matter (TOML) | Org | Org description |
|----------------------------------+------------------------------------+-----------------------------------------------------|
| =title = "foo"​= | =* foo= | Heading |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property (or =#+DATE:=) |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | Heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Heading set to TODO (or DRAFT) |
| =draft = false= | =* foo= | Heading *not* set to TODO (or DRAFT) |
| =weight = 123= | =:EXPORT_HUGO_WEIGHT: auto= | When set to =auto=, weight is auto-calculated. |
| =weight = 123= (in =[menu.foo]=) | =:EXPORT_HUGO_MENU: :menu foo= | Menu weight is auto-calculated unless specified. |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property (or =#+HUGO_AUTO_SET_LASTMODE: t=) |
|----------------------------------+------------------------------------+-----------------------------------------------------|
* Do I need to re-write my whole blog in Org?
If you are considering to try out =ox-hugo=, and if you have already
been using Hugo, it is normal for this thought to cross your mind:
Expand Down
Binary file added doc/images/one-post-per-file.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/images/one-post-per-subtree.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed doc/images/org-md.png
View file
Binary file not shown.
99 changes: 65 additions & 34 deletions doc/ox-hugo-manual.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ error backtrace,
:END:
=ox-hugo= is an Org exporter backend that exports Org to
[[https://gohugo.io/][Hugo]]-compatible Markdown ([[https://github.com/russross/blackfriday][Blackfriday]]). That also includes the
generation of front matter (in TOML or YAML format) for Hugo
generation of front-matter (in TOML or YAML format) for Hugo
posts.

Here is the blogging flow when using this package:
Expand All @@ -74,11 +74,17 @@ This project consists of =ox-blackfriday.el= too. It is a derivation
of [[https://github.com/larstvei/ox-gfm][=ox-gfm=]] with support added for Blackfriday Markdown tables and
many other tweaks. =ox-hugo= backend extends from this.

Before you read further, you can see below the outcome of an =ox-hugo=
export (Org on the left; exported Markdown with Hugo front-matter on
the right).
Before you read further, you can see below how =ox-hugo= translates
Org to Markdown (Org on the left; exported Markdown with Hugo
front-matter on the right).

#+INCLUDE: "./ox-hugo-manual.org::#screenshot" :only-contents t
*When writing posts as Org subtrees --*
#+INCLUDE: "./ox-hugo-manual.org::#screenshot-one-post-per-subtree" :only-contents t

*When writing each post as a separate Org file --*
#+INCLUDE: "./ox-hugo-manual.org::#screenshot-one-post-per-file" :only-contents t

#+INCLUDE: "./ox-hugo-manual.org::#org-blogging-flow-editorial" :only-contents t
** Why =ox-hugo=? :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Why ox-hugo?
Expand All @@ -94,7 +100,7 @@ complete feature-set. Org also allows stuff like:
- ..

Using Org for content writing allows using in-built Org features to
translate to Hugo front matter:
translate to Hugo front-matter:

- Org uses an outline structure and can inherit meta data (tags and
properties) from one subtree to children subtrees.
Expand Down Expand Up @@ -225,8 +231,28 @@ exported Markdown files.
directory. You can name it anything, but I prefer to name it
=content-org= ([[https://github.com/kaushalmodi/ox-hugo/tree/master/example-site][Example 1 -- =ox-hugo= example site]], [[https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io][Example 2 -- My
blog]]).
5. Create an Org file in there and follow the *Usage* section to
export it.
5. Create an Org file in there and follow the *Usage* section in the
[[https://github.com/kaushalmodi/ox-hugo#usage][README]] or [[https://github.com/kaushalmodi/ox-hugo/wiki/Usage][Wiki]] to export it.
** Translation of Org meta-data to Hugo front-matter :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Org meta-data to Hugo front-matter
:END:
When organizing the posts as Org *subtrees*, many Hugo front-matter
variables get set implicitly using the meta-data parsed from the posts
in Org.
|----------------------------------+------------------------------------+---------------------------------------------------------------------|
| Hugo front-matter (TOML) | Org | Org description |
|----------------------------------+------------------------------------+---------------------------------------------------------------------|
| =title = "foo"​= | =* foo= | Subtree heading (needs to have the =EXPORT_FILE_NAME= property set) |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property (or =#+DATE:=) |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | Heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Heading set to =TODO= (or =DRAFT=) |
| =draft = false= | =* foo= | Heading *not* set to =TODO= (or =DRAFT=) |
| =weight = 123= | =:EXPORT_HUGO_WEIGHT: auto= | When set to =auto=, weight is auto-calculated. |
| =weight = 123= (in =[menu.foo]=) | =:EXPORT_HUGO_MENU: :menu foo= | Menu weight is auto-calculated unless specified. |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property (or =#+HUGO_AUTO_SET_LASTMODE: t=) |
|----------------------------------+------------------------------------+---------------------------------------------------------------------|
** Formatting :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Formatting
Expand Down Expand Up @@ -256,25 +282,6 @@ heading and how it exports to Markdown in [[https://raw.githubusercontent.com/ka
/Org/ column in the table above, it is a bug with GitHub's Org
renderer.. just see those as *single* equal signs on each side of
/monospace/ instead.)
** Translation of Org meta-data to Hugo front matter :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Org meta-data to Hugo front matter
:END:
Many Hugo front matter variables get set implicitly using the
meta-data parsed from the posts in Org.
|----------------------------------+------------------------------------+-----------------------------------------------------|
| Hugo front matter (TOML) | Org | Org description |
|----------------------------------+------------------------------------+-----------------------------------------------------|
| =title = "foo"​= | =* foo= | Heading |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property (or =#+DATE:=) |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | Heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Heading set to TODO (or DRAFT) |
| =draft = false= | =* foo= | Heading *not* set to TODO (or DRAFT) |
| =weight = 123= | =:EXPORT_HUGO_WEIGHT: auto= | When set to =auto=, weight is auto-calculated. |
| =weight = 123= (in =[menu.foo]=) | =:EXPORT_HUGO_MENU: :menu foo= | Menu weight is auto-calculated unless specified. |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property (or =#+HUGO_AUTO_SET_LASTMODE: t=) |
|----------------------------------+------------------------------------+-----------------------------------------------------|
** Do I need to re-write my whole blog in Org? :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Do I need to re-write my whole blog in Org?
Expand Down Expand Up @@ -346,13 +353,37 @@ git clone https://github.com/kaushalmodi/ox-hugo.wiki.git

If changes are only to this Wiki, I believe you can push them directly
using =git= or manually edit those here.
** Screenshot :wiki:
** Screenshots :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Screenshots
:CUSTOM_ID: screenshots
:END:
*** One post per Org subtree (preferred)
:PROPERTIES:
:CUSTOM_ID: screenshot-one-post-per-subtree
:END:
[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-subtree.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-subtree.png]]
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content-org/screenshot-subtree-export-example.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content/writing-hugo-blog-in-org-subtree-export.md][Markdown]]
*** One post per Org file
:PROPERTIES:
:CUSTOM_ID: screenshot-one-post-per-file
:END:
[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-file.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/one-post-per-file.png]]
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content-org/writing-hugo-blog-in-org-file-export.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content/writing-hugo-blog-in-org-file-export.md][Markdown]]
*** Editorial
:PROPERTIES:
:EXPORT_FILE_NAME: Screenshot
:CUSTOM_ID: screenshot
:CUSTOM_ID: org-blogging-flow-editorial
:END:
[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/org-md.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/images/org-md.png]]
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content-org/screenshot-example.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/example-site/content/writing-hugo-blog-in-org.md][Markdown]]
The preferred way to organize the posts is as Org subtrees (also the
main reason to write this package, as nothing like that was out there)
as it makes the meta-data management for Hugo front-matter pretty
effortless.

If you are a /one Org-file per post/ type of a person, that flow works
too! Just note that in this flow many of those =#+HUGO_= properties
need to be managed manually.. just as one would manage the front-matter
in Markdown files --- See the Org versions in the above screenshots for
comparison.
** Org Capture Setup :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Org Capture Setup
Expand Down Expand Up @@ -411,8 +442,8 @@ Well.. you can do that with a minor 1-time setup.
case you add any Org footnotes, they go directly to that section
you created. Otherwise, in the absence of an existing /Footnotes/
heading, Org would create a new /Footnotes/ heading *at the end of
the file* -- so the /Local Variables/ will then no longer be at the
end of the file (and so they will stop working).
the file* -- so the /Local Variables/ heading will then no longer be
at the end of the file.
2. Then save the file, and do =revert-buffer=.
3. You will be prompted to add that =eval= line to your /Customize/
setup, hit =!= to permanently save that setting and prevent future
Expand Down
2 changes: 1 addition & 1 deletion doc/ox-hugo.wiki
Submodule ox-hugo.wiki updated from 3b40db to 286f17
Loading

0 comments on commit 8eae652

Please sign in to comment.