Add documentation for auto-publishing one Org file per post

[EnigmaCurry]

I wanted to use one Org-file per post, and I wanted to have auto-publishing whenever I saved the file. The docs mentioned that only worked with the one post per Org-subtree method, so I added the following to my config to get it to work..

If you could, please check to make sure the syntax highlighting is working properly on this. Although syntax highlighting is working great on the site I'm setting up, it is currently broken for me when I build the docs. (I'm using the packaged version of ox-hugo on elpa though, 20170922.1409, so maybe that's why it doesn't work on git master?)

Thank you so much for ox-hugo, it's exactly what I've been looking for.

[kaushalmodi]

• Can you please separate the bare lambda into a different function?
• And may be put an extra check that the file contains a #+TITLE? Because in the one Org file per post flow, that must be always be there, right?

As I realized, it is possible for a single site to use both: per file and per subtree flows.. so instead of blindly running org-hugo-export-to-md, might be better to check if the file looks like it is designed to export just one post.

[kaushalmodi]

The docs mentioned that only worked with the one post per Org-subtree method, so I added the following to my config to get it to work..

Thanks. My eventual plan is to have a "DWIM org hugo export fn" that exports the current valid subtree if :EXPORT_FILE_NAME is found, or the whole file (if #+TITLE is found). This can work in the mean time.

If you could, please check to make sure the syntax highlighting is working properly on this.

You mean in the Org buffer?

Although syntax highlighting is working great on the site I'm setting up, it is currently broken for me when I build the docs. (I'm using the packaged version of ox-hugo on elpa though, 20170922.1409, so maybe that's why it doesn't work on git master?)

I don't think that matters.. I am though not sure what you mean by broken syntax highlighting.. I just updated the doc/config.toml to work with Hugo 0.28 (as they switch to Chroma highlighter by default). Chroma doesn't yet work for the languages I work in.. so I have disabled it using the new option here: 4f4c1b8.

Thank you so much for ox-hugo, it's exactly what I've been looking for.

Many thanks for trying it out, and I am glad it's working for you :)

[kaushalmodi]

Better to use string-match-p as we don't care about the match side effects i.e. we don't plan to use match-string-no-properties, etc.

[EnigmaCurry]

Thanks, I'll work on the changes you suggested.

So this is what the docs look like after a fresh clone and just running 'hugo server'. Note the bad formatting in 'Step 2':

Since it's a fresh clone, I don't think it has anything to do with my current build of ox-hugo.

[kaushalmodi]

I see.. I am using Python Pygments for syntax highlighting.. you probably don't have that installed. So theoretically any code block will look like that. In item 1 of Step 1, the org block is showing fine because I have set Org blocks to show as Org Example blocks because Pygments doesn't support Org.

[kaushalmodi]

As a side note, have you assigned your copyright to FSF?

https://github.com/kaushalmodi/ox-hugo/blob/master/CONTRIBUTING.org

If you do not wish to do so, or cannot, I will update the documentation myself instead of merging this PR. At some point, when I get time, I need to figure out how to submit this package to GNU Elpa and do that. So the FSF assignment will be required from all contributors.

[EnigmaCurry]

I fixed it up per your recommendations.

I'm totally cool with assigning copyright, but it looks pretty involved! I'll look into it.

[kaushalmodi]

I fixed it up per your recommendations.

Thanks.

I'm totally cool with assigning copyright, but it looks pretty involved! I'll look into it.

You just need to send an email to assign@gnu.org asking that you'd like to assign your copyrights to FSF, and the ball will get rolling.

This is what I emailed them when I started with my FSF copyright assignment process:

Hi,

I visited this site: https://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html#Copyright-Papers

I would like to contribute to GNU Emacs.

What are the copyright papers that I would need to sign and return back to you?

And the process was over in a week, all via electronic media (email and PDF attachments).

[kaushalmodi]

Thanks for the contribution. I have merged your PR and then restructured it as the rest of the steps applied to both flows.

Also, notes on the changes I made to your code example:

• The (and fname ..) portion ensures that it runs only file buffers, not non-file buffers.. Just an extra check, even if this has to do with after-save-hook.
• I like the use of how-many!
• Use the content-org directory name to stay consistent with the rest of the doc
• Also hugo_base_dir to match the option #+HUGO_BASE_DIR.
• Wrap the fn for org-mode-hook into a separate function.
• Important: Add my/org-hugo-publish-current-buffer-as-post to after-save-hook only locally.. i.e. in Org files only. We don't want that to run unnecessarily when you are saving files in other major modes too.
• Use #' instead of plain ' for function symbols.

https://ox-hugo.netlify.com/doc/auto-export-on-saving/#one-post-per-org-file

[EnigmaCurry]

Awesome!

You might also consider simplifying step 2 and 3 with something like this:

(defconst my/hugo-dir (expand-file-name "~/hugo_base_dir") 
    "Root hugo site directory")

(defun hugo-server-start ()
    "Start hugo server in an inferior shell"
    (interactive)
    (let ((eshell-buffer-name "*hugo-server*"))
      (eshell)
      (eshell-return-to-prompt)
      (insert (concat "cd " my/hugo-dir))
      (eshell-send-input)
      (insert "hugo server -D --navigateToChanged")
      (eshell-send-input)
      (browse-url "http://localhost:1313")
      )
    )

[kaushalmodi]

Thanks for that suggestion. In my use case, I have many hugo servers running on various ports (even though I don't frequently update all of them.. personal/work blogs, technical docs, now this ox-hugo doc, etc.). So I just have a dedicated tmux window with all these servers running in multiple panes.

That way they can live 'forever' and don't get killed when I kill emacs (I like updating packages, building Org and Emacs from master, so I restart emacs at least once a day :) ).

It will be good to have a separate post subtree on the topic of "Starting hugo server from within emacs". Along with your code, you can also add references to https://github.com/yewton/hugo.el and https://github.com/masasam/emacs-easy-hugo.

[kaushalmodi]

Are you going to work on the FSF copyright assignment?

[EnigmaCurry]

I've sent them an email.