From mboxrd@z Thu Jan 1 00:00:00 1970 From: Kaushal Modi Subject: Re: Moving from Jekyll to Orgmode Date: Mon, 30 Apr 2018 22:43:56 +0000 Message-ID: References: <1524949519.21032.171.camel@gmail.com> <874ljump59.fsf@atmarama.com> <02CE4F97-08E0-4A50-9CE5-68D0D7712ACD@zzamboni.org> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="000000000000763de0056b189728" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:55177) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fDHWl-0008EF-JR for emacs-orgmode@gnu.org; Mon, 30 Apr 2018 18:44:13 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fDHWj-0000ta-KC for emacs-orgmode@gnu.org; Mon, 30 Apr 2018 18:44:11 -0400 Received: from mail-yb0-x22d.google.com ([2607:f8b0:4002:c09::22d]:43526) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fDHWj-0000tV-CF for emacs-orgmode@gnu.org; Mon, 30 Apr 2018 18:44:09 -0400 Received: by mail-yb0-x22d.google.com with SMTP id x145-v6so2788455ybg.10 for ; Mon, 30 Apr 2018 15:44:08 -0700 (PDT) In-Reply-To: <02CE4F97-08E0-4A50-9CE5-68D0D7712ACD@zzamboni.org> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Diego Zamboni Cc: Luis Roca , emacs-orgmode@gnu.org --000000000000763de0056b189728 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi Diego, On Mon, Apr 30, 2018 at 4:29 PM Diego Zamboni wrote: > > ox-hugo takes a different approach: it uses org-mode=E2=80=99s ox-markdow= n > exporter to produce Markdown from the org source, so that Hugo processes = a > Markdown file. This makes a big difference, as each tool is processing it= s > own native format: org-mode processes org, and Hugo processes Markdown. > That's very well said :) > Thanks to this, you can even include Hugo shortcodes ( > https://gohugo.io/content-management/shortcodes/) in your org-mode > source, and they will be passed untouched to Hugo (this is not entirely > advisable as it makes your source Hugo-specific, but it=E2=80=99s doable = if you > want it). > Correct. The aim of ox-hugo is to allow any Org document to be easily exportable to Hugo, while also allowing the same document to be reusable for other export formats too. So I don't recommend embedding Hugo shortcodes directly in Org files (even if they work.. not guaranteeing that such embedded Hugo shortcodes will always work). But shortcodes are still supported, though in a different style, leveraging the Org special blocks. That feature is yet undocumented. But it is fully implemented, tested (and used by me). See https://github.com/kaushalmodi/ox-hugo/issues/126 for more info. > Another very nice ox-hugo feature is its =E2=80=9COne post per Org subtre= e=E2=80=9D mode ( > https://ox-hugo.scripter.co/#screenshot-one-post-per-subtree), in which > you keep your entire post tree (in fact, you could keep your entire > website) in a single Org file. I was skeptical about this at first (who > wants to keep *everything* in a single file), but in practice it works ve= ry > well, and allows you to have tags/categories or other attributes per > subtree, so you don=E2=80=99t have to repeat them on every post. > That's the primary reason why I started working on ox-hugo. I couldn't bear the manual labor of copy/pasting/syncing of front-matter across separate Markdown files. I always suggest people to try the "per-subtree blogging flow" because Org subtree structure, property and tag inheritance so much reduce that manual effort. See here on how various properties and tags translate to Hugo front-matter -> https://ox-hugo.scripter.co/doc/org-meta-data-to-hugo-front-matter/#for-sub= tree-based-exports . I also have this little annotated diagram: https://discourse-cdn-sjc2.com/standard12/uploads/gohugo/original/2X/8/8dd4= af3e103c3a691a71356aa3f91bfe1019ebae.png > If you really want to keep each post in a separate file, that is doable a= s > well. The ox-hugo website has a lot of very useful information. > > Finally, you can do the transition gradually - for my website, I had year= s > of accumulated Markdown files from my adventures with Jekyll, Octopress a= nd > later Hugo. Those are still in place, and I have started only putting my > new posts in an org file which ox-hugo processes. Since those are convert= ed > to Markdown files, they end up alongside the old hand-crafted files, and > Hugo just processes them all together. > That too! Looks like you hit all the awesome points :) My scripter.co site source also contains of few dozen old Markdown posts. New stuff is written in Org and exported to Markdown using ox-hugo which live right along the old Markdown content... and everything just works. > I really recommend ox-hugo, Kaushal has done a fantastic job and he is > also really helpful and responsive with questions. > Thanks for this heavy recommendation. Working on this project and supporting/making it more robust based on user feedback has been great pleasure. Tip: I learned a lot by reading the source files for > https://ox-hugo.scripter.co/ and for https://scripter.co/, both of which > are kept in ox-hugo structure. You can find pointers to those and some > other examples (including my own websites, zzamboni.org and cf-learn.info= ) > at https://ox-hugo.scripter.co/doc/examples/ > Yes! The list of contributors on that Real World Examples page is growing day by day. And finally, some clarification about things mentioned in other parts of this thread: - Using Hugo does *not* require you to know the Go language. You just learn the Go templating syntax. And that too, if you want to start by tweaking and designing Hugo themes. You can always pick one of the 200+ Hugo themes, and get your blog started, and then revisit writing your own theme at a later time. - It doesn't even require you to install the Go toolchain (though it's not difficult, you just unzip an archive). - "Installing" hugo is a matter of a single wget of the archive for the OS of your choice from here: https://github.com/gohugoio/hugo/releases, and then unarchiving that to somewhere in your PATH. Apart of the binary-static-ness of the hugo static site generator, another reason it appealed to me is that the Go templating syntax feels a bit /lispy/. For example, I use this: {{ $.Scratch.Set "__repo_updated_time" (index (index (index (index $repo_json "commit") "commit") "committer") "date") }} which extracts the commit date by the committer (not author) using GitHub API for the "Last updated" column on the Real World Examples page: https://ox-hugo.scripter.co/doc/examples/ (hopefully someone didn't think I was manually updating all those dates :P) In summary, ox-hugo allows you to use the best tools for each task: (1) content writing in Org, and (2) mass HTML/RSS/JSON/etc. generation using Hugo. The former wins in having a concise Org document where the Org features of macros, tag/property inheritance, Org babel, etc. can be leveraged. The latter wins in creating the *whole* site containing literally hundreds of pages (posts, lists, feeds, search index, JSON feeds, aliased pages, whatnot) in a matter of *a second or two*. Kaushal --=20 Kaushal Modi --000000000000763de0056b189728 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Diego,

On Mon, Apr 30, 2018 at 4:29 PM Diego Zamboni <diego@zzamboni.org&= gt; wrote:

ox-hugo takes a different= approach: it uses org-mode=E2=80=99s ox-markdown exporter to produce Markd= own from the org source, so that Hugo processes a Markdown file. This makes= a big difference, as each tool is processing its own native format: org-mo= de processes org, and Hugo processes Markdown.

That's very well said :)
=C2=A0
Thanks to this, you can even include Hugo sho= rtcodes (https://gohugo.io/content-management/shortcodes/) in your = org-mode source, and they will be passed untouched to Hugo (this is not ent= irely advisable as it makes your source Hugo-specific, but it=E2=80=99s doa= ble if you want it).

Correct= . The aim of ox-hugo is to allow any Org document to be easily exportable t= o Hugo, while also allowing the same document to be reusable for other expo= rt formats too.

So I don't recommend embedding Hugo s= hortcodes directly in Org files (even if they work.. not guaranteeing that = such embedded Hugo shortcodes will always work). But shortcodes are still s= upported, though in a different style, leveraging the Org special blocks. T= hat feature is yet undocumented. But it is fully implemented, tested (and u= sed by me). See https://github.com/kaushalmodi/ox-hugo/issues/126 for more info.
=
=C2=A0
Another very= nice ox-hugo feature is its =E2=80=9COne post per Org subtree=E2=80=9D mod= e (https://ox-hugo.scripter.co/#screenshot-one-post-per-sub= tree), in which you keep your entire post tree (in fact, you could keep= your entire website) in a single Org file. I was skeptical about this at f= irst (who wants to keep *everything* in a single file), but in practice it = works very well, and allows you to have tags/categories or other attributes= per subtree, so you don=E2=80=99t have to repeat them on every post.
=

That's the primary reason why I = started working on ox-hugo. I couldn't bear the manual labor of copy/pa= sting/syncing of front-matter across separate Markdown files. I always sugg= est people to try the "per-subtree blogging flow" because Org sub= tree structure, property and tag inheritance so much reduce that manual eff= ort. See here on how various properties and tags translate to Hugo front-ma= tter -> https://ox-hugo.scripter.co/doc/o= rg-meta-data-to-hugo-front-matter/#for-subtree-based-exports.


That too! Looks like you hit all the awesome points :) My scripter.co site source also contains of few dozen old M= arkdown posts. New stuff is written in Org and exported to Markdown using o= x-hugo which live right along the old Markdown content... and everything ju= st works.
=C2=A0
I really = recommend ox-hugo,=C2=A0Kaushal has done a fantastic job and he is also rea= lly helpful and responsive with questions.
Thanks for this heavy recommendation. Working on this project a= nd supporting/making it more robust based on user feedback has been great p= leasure.

Tip: I le= arned a lot by reading the source files for=C2=A0https://ox-hugo.scripter.co/=C2=A0and = for=C2=A0https://scripte= r.co/, both of which are kept in ox-hugo structure. You can find pointe= rs to those and some other examples (including my own websites, zzamboni.org and cf-learn.info) at=C2=A0https://ox-hugo= .scripter.co/doc/examples/

= Yes! The list of contributors on that Real World Examples page is growing d= ay by day.

And finally, some clarification about things m= entioned in other parts of this thread:

- Using Hugo does= *not* require you to know the Go language. You just learn the Go templatin= g syntax. And that too, if you want to start by tweaking and designing Hugo= themes. You can always pick one of the 200+ Hugo themes, and get your blog= started, and then revisit writing your own theme at a later time.
- It doesn't even require you to install the Go toolchain (though= it's not difficult, you just unzip an archive).
- "= Installing" hugo is a matter of a single wget of the archive for the O= S of your choice from here: https://github.com/gohugoio/hugo/releases, and then unarchiving = that to somewhere in your PATH.

Apart of the binary-static-ness of the hugo static site generator, anoth= er reason it appealed to me is that the Go templating syntax feels a bit /l= ispy/. For example, I use this:

{{ $.Scratch.Set "__repo_update= d_time" (index (index (index (index $repo_json "commit") &qu= ot;commit") "committer") "date") }}

which extracts the commit date by = the committer (not author) using GitHub API for the "Last updated"= ; column on the Real World Examples page: https://ox-hugo.scripter.co/doc/examples/ (hopeful= ly someone didn't think I was manually updating all those dates :P)
=

In summary, ox-hugo al= lows you to use the best tools for each task: (1) content writing in Org, a= nd (2) mass HTML/RSS/JSON/etc. generation using Hugo. The former wins in ha= ving a concise Org document where the Org features of macros, tag/property = inheritance, Org babel, etc. can be leveraged. The latter wins in creating = the *whole* site containing literally hundreds of pages (posts, lists, feed= s, search index, JSON feeds, aliased pages, whatnot) in a matter of *a seco= nd or two*.

Kaushal
--

Kaushal Modi

--000000000000763de0056b189728--