Skip to content

Commit

Permalink
Improve: Now C-c C-e H H works for both per-subtree/per-file flows
Browse files Browse the repository at this point in the history 
* ox-hugo.el:
  - Obsolete org-hugo-export-subtree-* functions and replace them with
    org-hugo-export-wim-* (What I Mean) functions. See the doc string
    of org-hugo-export-wim-to-md for details.
  - Fix the return values of org-hugo-export-as-md,
    org-hugo-export-to-md, org-hugo-publish-to-md and the new
    org-hugo-export-wim-to-md. Update their doc strings.
  - (org-hugo-export-wim-to-md): This new function now exports using
    per-file flow or per-subtree flow automatically. Improve the
    messages printed during export.
  - (org-hugo-export-to-md): Allow Org files exported using per-file
    approach not get exported based on tags. See "Marking files to not
    be exported" in documentation for details.
  - (org-hugo-publish-to-md): Comment out this function. It doesn't
    work (If someone was using it, please open an issue so that I can
    uncomment that.)
* setup-ox-hugo.el:
  - New function org-hugo-export-all-wim-to-md that uses the new
    org-hugo-export-wim-to-md function.
  - Stop printing too many messages when loading emacs.
  - Increase org-export-headline-levels to 4.
  - Don't export files and subtrees tagged
    "dont_export_during_make_test" during "make test".
* Makefile:
  - Now uses the new org-hugo-export-all-wim-to-md function
    defined above, and thus no need to hard-code subtree-based and
    file-based Org files.
  - New rule do_test replaces the old test_subtree and test_file
    rules.
  - New rule md1 replaces the old mdtree and mdfile rules.
* ox-hugo-manual.org:
  - Add section on "Marking files to not be exported"
  - Update "Auto-export on Saving" to reflect the refactoring to
    org-hugo-export-wim-* functions.
  - Update bindings descriptions.
* Misc tests: Make changes to match the above changes.

This commit helps towards
#39. Now Org files can be
exported seamlessly using the per-file or per-subtree flow using a
Makefile like one in this repo.
  • Loading branch information
@kaushalmodi
kaushalmodi committed Dec 1, 2017
1 parent 447d361 commit b1b5d28
Show file tree
Hide file tree
Showing 14 changed files with 396 additions and 276 deletions.
74 changes: 20 additions & 54 deletions Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Time-stamp: <2017-11-29 14:56:39 kmodi>
# Time-stamp: <2017-12-01 10:44:11 kmodi>

# Makefile to export org documents to md for Hugo from the command line
# Run just "make" to see usage examples.
Expand Down Expand Up @@ -53,42 +53,28 @@ OX_HUGO_TEST_SITE_DIR=$(OX_HUGO_TEST_DIR)/site

# Directory containing Org files for the test site
OX_HUGO_TEST_ORG_DIR=$(OX_HUGO_TEST_SITE_DIR)/content-org
# https://stackoverflow.com/a/3774731/1219634
# Note that the use of immediate assignment := rather than recursive
# assignment = is important here: you do not want to be running the
# shell escape every time SOURCES is inspected by make.
test_org_files := $(shell find ${OX_HUGO_TEST_ORG_DIR} -type f -name '*.org')

# Path to the Org file relative to $(OX_HUGO_TEST_ORG_DIR)
# Path to the Org file (relative to pwd, or absolute)
ORG_FILE=

# Function to be run in emacs --batch
FUNC=

test_check=1

subtree_test_files = all-posts.org \
construct-hugo-front-matter-from-menu-meta-data.org \
src-blocks-with-highlight-shortcode.org \
mandatory-EXPORT_FILE_NAME-for-subtree-export.org \
hugo-menu-as-keyword.org \
tags-keyword.org \
hugo-weight-as-keyword-auto-calc.org \
deep-nesting.org \
images-in-content/images-in-content.org

file_test_files = single-posts/post-toml.org \
single-posts/post-yaml.org \
single-posts/post-draft.org \
single-posts/hugo-auto-weight-ineffective-for-per-file-exports.org \
single-posts/export-without-emphasize.org \
images-in-content/post3/post3.org \
images-in-content/post4/post4.org

# Cannot run tests on the following files, because:
# - auto-set-lastmod.org - the lastmod field will always get updated.
# - screenshot-subtree-export-example.org - sets the org-hugo-footer using Local Variables.
# - writing-hugo-blog-in-org-file-export.org - sets the org-hugo-footer using Local Variables.

.PHONY: help emacs-batch mdtree mdfile vcheck hugo hugo_doc hugo_test serve server diff \
.PHONY: help emacs-batch md1 vcheck hugo hugo_doc hugo_test serve server diff \
test md testmkgold \
test_subtree $(subtree_test_files) \
test_file $(file_test_files) \
do_test $(test_org_files) \
doc_md doc_gh doc \
ctemp diffgolden clean

Expand Down Expand Up @@ -123,19 +109,12 @@ emacs-batch:
(when (> (length \"$(TIMEZONE)\") 0) (setenv \"TZ\" \"$(TIMEZONE)\"))\
(setq-default make-backup-files nil)\
(load-file (expand-file-name \"setup-ox-hugo.el\" \"$(OX_HUGO_TEST_DIR)\"))\
)" $(ORG_FILE_DIR)/$(ORG_FILE) \
)" $(ORG_FILE) \
-f $(FUNC) \
--kill

mdtree:
@echo "[ox-hugo] Exporting Org to Md in 'Subtree' mode .."
@$(MAKE) emacs-batch FUNC=org-hugo-export-all-subtrees-to-md
@echo "[ox-hugo] Done"

mdfile:
@echo "[ox-hugo] Exporting Org to Md in 'File' mode .."
@$(MAKE) emacs-batch FUNC=org-hugo-export-to-md
@echo "[ox-hugo] Done"
md1:
@$(MAKE) emacs-batch FUNC=org-hugo-export-all-wim-to-md

vcheck:
ifeq ("$(EMACS_exists)","")
Expand Down Expand Up @@ -174,11 +153,10 @@ serve server: vcheck
diff:
@git diff

test: vcheck testmkgold test_subtree test_file
test: vcheck testmkgold do_test

md:
@$(MAKE) test_subtree test_check=0
@$(MAKE) test_file test_check=0
@$(MAKE) do_test test_check=0

# Get rid of all changes in $(OX_HUGO_TEST_SITE_DIR)/content.
# https://stackoverflow.com/a/16589534/1219634
Expand All @@ -187,35 +165,23 @@ testmkgold:
@rm -rf $(OX_HUGO_TEST_SITE_DIR)/content-golden
@cp -rf $(OX_HUGO_TEST_SITE_DIR)/content $(OX_HUGO_TEST_SITE_DIR)/content-golden

# Run the mdtree + diffgolden rules in loop on all of $(subtree_test_files)
# Run the md1 + diffgolden rules in loop on all of $(subtree_test_files)
# https://stackoverflow.com/a/37748952/1219634
test_subtree: $(subtree_test_files)
$(subtree_test_files):
@$(MAKE) mdtree ORG_FILE=$@ \
ORG_FILE_DIR=$(OX_HUGO_TEST_ORG_DIR) \
TIMEZONE=UTC # Use UTC/Universal time zone for tests
ifeq ($(test_check),1)
@$(MAKE) diffgolden
endif

# Run the mdfile + diffgolden rules in loop on all of $(file_test_files)
test_file: $(file_test_files)
$(file_test_files):
@$(MAKE) mdfile ORG_FILE=$@ \
ORG_FILE_DIR=$(OX_HUGO_TEST_ORG_DIR) \
TIMEZONE=UTC # Use UTC/Universal time zone for tests
do_test: $(test_org_files)
$(test_org_files):
@$(MAKE) md1 ORG_FILE=$@ TIMEZONE=UTC # Use UTC/Universal time zone for tests
ifeq ($(test_check),1)
@$(MAKE) diffgolden
endif

doc_md:
@echo "[Doc Site] Generating ox-hugo Documentation Site content .."
@$(MAKE) mdtree ORG_FILE=ox-hugo-manual.org ORG_FILE_DIR=./doc
@$(MAKE) md1 ORG_FILE=./doc/ox-hugo-manual.org
@echo "[Doc Site] Done"

doc_gh:
@echo "[GitHub Docs] Generating README.org and CONTRIBUTING.org for GitHub .."
@$(MAKE) emacs-batch FUNC=ox-hugo-export-gh-doc ORG_FILE=github-files.org ORG_FILE_DIR=./doc
@$(MAKE) emacs-batch FUNC=ox-hugo-export-gh-doc ORG_FILE=./doc/github-files.org
@echo "[GitHub Docs] Done"

doc: doc_md hugo_doc doc_gh
Expand Down
152 changes: 92 additions & 60 deletions doc/ox-hugo-manual.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -316,14 +316,24 @@ Before you export check that these properties are set as you need:
used by this package to figure out where the current post starts.
*** Export bindings
The common =ox-hugo= export bindings are:
|---------------+-------------------------------------------------------------------------------------|
| Binding | Description |
|---------------+-------------------------------------------------------------------------------------|
| =C-c C-e H H= | Export only the current /valid/ subtree (has the =EXPORT_FILE_NAME= property set) |
| =C-c C-e H A= | Export *all* /valid/ subtrees (those that have the =EXPORT_FILE_NAME= property set) |
|---------------+-------------------------------------------------------------------------------------|
| =C-c C-e H h= | Export the whole Org file to a single post |
|---------------+-------------------------------------------------------------------------------------|
**** For both one-post-per-subtree and one-post-per-file flows
- =C-c C-e H H= :: Export "What I Mean".
- If point is in a /valid Hugo post subtree/, export that
subtree to a Hugo post in Markdown.

A /valid Hugo post subtree/ is an Org subtree has the
=EXPORT_FILE_NAME= property set.
- If the file is intended to be exported as a whole i.e. it must have
the #+TITLE keyword set, export the whole Org file a Hugo post in
Markdown.
- =C-c C-e H A= :: Export *all* "What I Mean"
- If the Org file has one or more 'valid Hugo post subtrees', export
them to Hugo posts in Markdown.
- If the file is intended to be exported as a whole (no 'valid Hugo
post subtrees' at all) i.e. it must have the #+TITLE keyword set,
export the whole Org file a Hugo post in Markdown.
**** For only the one-post-per-file flow
- =C-c C-e H h= :: Export the Org file to a Hugo post in Markdown.
*** Customization Options
Do =M-x customize-group=, and select =org-export-hugo= to see the
available customization options for this package.
Expand Down Expand Up @@ -654,7 +664,7 @@ exported Markdown files.
:PROPERTIES:
:EXPORT_FILE_NAME: org-meta-data-to-hugo-front-matter
:END:
**** For subtree exports (=C-c C-e H H= or =C-c C-e H A=)
**** For subtree exports
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.
Expand All @@ -680,7 +690,7 @@ set.
***** Notes
- Precedence for =date= parsing: =CLOSED= subtree property /more than/
=EXPORT_DATE= subtree property /more than/ =#+DATE:= keyword.
**** For complete-file exports (=C-c C-e H h=)
**** For complete-file exports
|----------------------------------+--------------------------------------|
| Hugo front-matter (TOML) | Org |
|----------------------------------+--------------------------------------|
Expand Down Expand Up @@ -917,6 +927,18 @@ If the =EXPORT_HUGO_TAGS= property is set for a valid Hugo post
subtree, the value of that property will *completely override* the Org
tags set even on that subtree, the inherited values of Org-style tags
from parent headlines and even =#+FILETAGS=.
****** Marking files to not be exported
Note that if you want to prevent a file from getting exported, you can
assign a special tag to the whole file (example: =no_no_dont_export=),
but that tag *has to be set using the =#+FILETAGS= keyword*
(=#+HUGO_TAGS= keyword is *only* for setting the tags in Hugo
front-matter). This applies to both, file-based and subtree-based[fn:2]
export flows.

Then in your batch export setup, add that special tag to the
=org-export-exclude-tags= variable. You can grep through this repo for
the special tag =dont_export_during_make_test= that is used to mark
few Org files to not be exported during =make test=.
****** Why use =#+FILETAGS= and not =#+TAGS=?
- About =#+FILETAGS= -- [[http://orgmode.org/manual/Tag-inheritance.html][Tag Inheritance]] or =C-h i g (org) Tag
inheritance=
Expand Down Expand Up @@ -1034,58 +1056,63 @@ Hugo-rendered post each time you saved your post in Org?

Well.. you can do that with these steps:
**** First time setup
The first time setup varies between the /per-subtree export flow/ and
/per-file export flow/.
***** One post per Org subtree
***** =after-save-hook= setup for both /per-subtree/ and /per-file/ flows
This step applies whether you intend to use the /per-subtree export
flow/ or the /per-file/ export flow.
****** Step 1a: Set up the =after-save-hook=
1. Add below to the very-end of your posts Org file:
#+BEGIN_SRC org
* Footnotes
* COMMENT Local Variables :ARCHIVE:
# Local Variables:
# eval: (add-hook 'after-save-hook #'org-hugo-export-subtree-to-md-after-save :append :local)
# End:
#+END_SRC

Here I recommend adding the =* Footnotes= header too so that in
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/ 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
prompts.
1. Add below to the very-end of your Org file:
#+BEGIN_SRC org
,* Footnotes
,* COMMENT Local Variables :ARCHIVE:
# Local Variables:
# eval: (add-hook 'after-save-hook #'org-hugo-export-wim-to-md-after-save :append :local)
# End:
#+END_SRC
*About Footnotes*: Here I recommend adding the =* Footnotes= header
too so that in case you add any Org footnotes, they go directly to
that section you created. Otherwise, Org will auto-create a new
/Footnotes/ heading *at the end of the file*.. and the /Local
Variables/ heading would 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
prompts.
****** Step 1b: Prevent auto-export during Org Capture
You might find this step useful if you choose to write new posts
using =org-capture= as explained in the {{{doc(org-capture-setup,/Org
Capture Setup/)}}} section.

After saving the below to your emacs config and evaluating it,
auto-exports will be prevented when saving a new post created using
Org Capture.
#+BEGIN_SRC emacs-lisp
(with-eval-after-load 'org-capture
;; Do not cause auto Org->Hugo export to happen when saving captures
(defun modi/org-capture--remove-auto-org-to-hugo-export-maybe ()
"Function for `org-capture-before-finalize-hook'.
Disable `org-hugo-export-subtree-to-md-after-save'."
(setq org-hugo-allow-export-after-save nil))

(defun modi/org-capture--add-auto-org-to-hugo-export-maybe ()
"Function for `org-capture-after-finalize-hook'.
Enable `org-hugo-export-subtree-to-md-after-save'."
(setq org-hugo-allow-export-after-save t))

(add-hook 'org-capture-before-finalize-hook #'modi/org-capture--remove-auto-org-to-hugo-export-maybe)
(add-hook 'org-capture-after-finalize-hook #'modi/org-capture--add-auto-org-to-hugo-export-maybe))
#+END_SRC
***** One post per Org file
****** Step 1: Set up the =after-save-hook=
If you use a seperate Org file for each blog post, you can add the
below to your config:
While this sub-step is useful for the /per-subtree/ export flow, it
won't hurt to implement even if you are using the /per-file/ flow.

This step is useful if you choose to write new posts using
=org-capture= as explained in the {{{doc(org-capture-setup,/Org
Capture Setup/)}}} section.

After saving the below to your emacs config and evaluating it,
auto-exports will be prevented when saving a new post created using
Org Capture.

/If you don't do the below, auto-exports would happen as soon as you
=C-c C-c= on your initial capture.. which could get annoying./
#+BEGIN_SRC emacs-lisp
(with-eval-after-load 'org-capture
;; Do not cause auto Org->Hugo export to happen when saving captures
(defun modi/org-capture--remove-auto-org-to-hugo-export-maybe ()
"Function for `org-capture-before-finalize-hook'.
Disable `org-hugo-export-wim-to-md-after-save'."
(setq org-hugo-allow-export-after-save nil))

(defun modi/org-capture--add-auto-org-to-hugo-export-maybe ()
"Function for `org-capture-after-finalize-hook'.
Enable `org-hugo-export-wim-to-md-after-save'."
(setq org-hugo-allow-export-after-save t))

(add-hook 'org-capture-before-finalize-hook #'modi/org-capture--remove-auto-org-to-hugo-export-maybe)
(add-hook 'org-capture-after-finalize-hook #'modi/org-capture--add-auto-org-to-hugo-export-maybe))
#+END_SRC
***** Alternative =after-save-hook= setup only for /per-file/ flow
This step applies *only* to the /per-file/ export flow.
****** Step 1: Set up the =after-save-hook= (only for /per-file/ flow)
If you use a seperate Org file for each blog post, you can add the
below to your config *instead* of doing the above. Skip /Step 1b/
below altogether if you use this alternative.
#+BEGIN_SRC emacs-lisp
(use-package ox-hugo
:ensure t
Expand Down Expand Up @@ -1292,6 +1319,11 @@ for writing your posts in Org, there are examples for both in the
#+INCLUDE: "./ox-hugo-manual.org::#test" :only-contents t
* Footnotes

[fn:2] For only subtree-based exports, you can set that special tag as
Org style tags too. Example: ~* I don't want to export this post
:no_no_dont_export:~.. and don't forget to add that tag to
=org-export-exclude-tags= too!

[fn:1] To understand why the attachment files get copied to the
=static/ox-hugo/= directory, have a look at the documentation for
{{{doc(image-links#references-to-files-outside-the-static-directory,referencing
Expand All @@ -1301,5 +1333,5 @@ files outside static directory)}}}.
# fill-column: 70
# eval: (auto-fill-mode 1)
# eval: (toggle-truncate-lines 1)
# eval: (add-hook 'after-save-hook #'org-hugo-export-subtree-to-md-after-save :append :local)
# eval: (add-hook 'after-save-hook #'org-hugo-export-wim-to-md-after-save :append :local)
# End:
Loading

0 comments on commit b1b5d28

Please sign in to comment.