Moving from Jekyll to Orgmode

Moving from Jekyll to Orgmode

[ST]

Hello,

I would like to rewrite my website using Orgmode (till now I used
Jekyll). It would be nice if you could help me with following questions:

1. could somebody, please, point me to a tutorial on how to create a
multilingual site? Like the orgmode.org with EN:FR:JA. Ideally it would
be if one would have page-aware language switch, i.e. if one is on the
page orgmode.org/fr/features.html and clicks JA he will be redirected to
orgmode.org/ja/features.html (and not .../ja/index.html as it is now)...

2. how can one create "prettified" links, i.e. /features/ instead
of /features.html ? Basically during the website generation for the file
features.org a directory `features` needs to be created and the html
file placed into `features/index.html` ... Is there a tutorial on how to
do that?

3. is there a free modern "corporate" style theme for org-mode?

Thank you!

Re: Moving from Jekyll to Orgmode

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 3257 bytes --]

Hi,

> I would like to rewrite my website using Orgmode (till now I used
> Jekyll). It would be nice if you could help me with following questions:

Org-mode is not really a website-publishing tool like Jekyll, although it can be part of the chain. Org-mode at its core is a markup language, although with considerable tooling support from org-mode and related tools in Emacs.

Org-mode would be equivalent to Markdown in this respect. You still need to use a tool to generate/publish your website.

My current favorite is Hugo (http://gohugo.io/ <http://gohugo.io/>) which, just like Jekyll, generated a static website, but has a lot of very nice features.

So, the first step would be to migrate your website from Jekyll to Hugo (https://gohugo.io/tools/migrations/#jekyll <https://gohugo.io/tools/migrations/#jekyll>), including built-in support in Hugo (https://gohugo.io/commands/hugo_import_jekyll/ <https://gohugo.io/commands/hugo_import_jekyll/>). At this point, your posts would still be in Markdown format, but once in Hugo, you can start moving them over to org-mode. My recommendation would be to use the excellent ox-hugo (https://ox-hugo.scripter.co/ <https://ox-hugo.scripter.co/>), which allows you to keep your source files in org-mode but generate proper Markdown files for Hugo.

My answers below assume the above.

> 1. could somebody, please, point me to a tutorial on how to create a
> multilingual site? Like the orgmode.org with EN:FR:JA. Ideally it would
> be if one would have page-aware language switch, i.e. if one is on the
> page orgmode.org/fr/features.html and clicks JA he will be redirected to
> orgmode.org/ja/features.html (and not .../ja/index.html as it is now)…

Hugo has built-in support for multilingual sites: https://gohugo.io/content-management/multilingual/ <https://gohugo.io/content-management/multilingual/> - I’ve never used it so I don’t know how well it works.

> 2. how can one create "prettified" links, i.e. /features/ instead
> of /features.html ? Basically during the website generation for the file
> features.org a directory `features` needs to be created and the html
> file placed into `features/index.html` ... Is there a tutorial on how to
> do that?

Hugo does this by default, but has a lot of options for how URLs are generated: https://gohugo.io/content-management/urls/ <https://gohugo.io/content-management/urls/>

> 3. is there a free modern "corporate" style theme for org-mode?

Org-mode doesn’t have themes, but Hugo does: https://themes.gohugo.io/ <https://themes.gohugo.io/>

I hope this helps. Feel free to look at the source for my website (http://zzamboni.org/ <http://zzamboni.org/>) for inspiration: https://github.com/zzamboni/zzamboni.org <https://github.com/zzamboni/zzamboni.org>. I only recently started migration to org-mode/ox-hugo. You can find all my old posts at https://github.com/zzamboni/zzamboni.org/tree/master/content <https://github.com/zzamboni/zzamboni.org/tree/master/content>, and the newer ones, generated from an org-mode file, at https://github.com/zzamboni/zzamboni.org/blob/master/content-org/zzamboni.org <https://github.com/zzamboni/zzamboni.org/blob/master/content-org/zzamboni.org>.

Best,
—Diego


[-- Attachment #2: Type: text/html, Size: 4835 bytes --]

Re: Moving from Jekyll to Orgmode

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 908 bytes --]


> I hope this helps. Feel free to look at the source for my website (http://zzamboni.org/ <http://zzamboni.org/>) for inspiration: https://github.com/zzamboni/zzamboni.org <https://github.com/zzamboni/zzamboni.org>. I only recently started migration to org-mode/ox-hugo. You can find all my old posts at https://github.com/zzamboni/zzamboni.org/tree/master/content <https://github.com/zzamboni/zzamboni.org/tree/master/content>, and the newer ones, generated from an org-mode file, at https://github.com/zzamboni/zzamboni.org/blob/master/content-org/zzamboni.org <https://github.com/zzamboni/zzamboni.org/blob/master/content-org/zzamboni.org>.

I meant to say: “the source for the newer (recent) ones is the org-mode file at https://github.com/zzamboni/zzamboni.org/blob/master/content-org/zzamboni.org <https://github.com/zzamboni/zzamboni.org/blob/master/content-org/zzamboni.org>”.

—Diego


[-- Attachment #2: Type: text/html, Size: 1901 bytes --]

Re: Moving from Jekyll to Orgmode

[Scott Randby]

On 04/28/2018 05:40 PM, Diego Zamboni wrote:
> 
> Org-mode is not really a website-publishing tool like Jekyll, although it can be part of the chain. Org-mode at its core is a markup language, although with considerable tooling support from org-mode and related tools in Emacs.
> 

I think Org is a good website publishing tool in many ways. I've been using it for making and publishing my website since 2010. Sure, it has some limitations, but I think it can be made to work nicely for a lot of types of sites. But I do agree that the Org/Hugo combination is really good.

Scott Randby

Re: Moving from Jekyll to Orgmode

[ST]

Hi Scott,

thank you, and all other responders, for the shared information. The
reason I want to leave Jekyll is because I don't want to depend on a
tool that relies on language (Ruby)/environment that I don't know/use
(in this respect Hugo is the same for me). I prefer something more
simplistic, even though if I'll have to invest some time for it to work
initially. Those 3 features I've mentioned are almost all I need, more
or less.

Could you, please, share your website publishing workflow (considering
the 3 issues I've mentioned)?

Thank you!

On Sat, 2018-04-28 at 18:13 -0400, Scott Randby wrote:
> On 04/28/2018 05:40 PM, Diego Zamboni wrote:
> > 
> > Org-mode is not really a website-publishing tool like Jekyll, although it can be part of the chain. Org-mode at its core is a markup language, although with considerable tooling support from org-mode and related tools in Emacs.
> > 
> 
> I think Org is a good website publishing tool in many ways. I've been using it for making and publishing my website since 2010. Sure, it has some limitations, but I think it can be made to work nicely for a lot of types of sites. But I do agree that the Org/Hugo combination is really good.
> 
> Scott Randby
> 

Re: Moving from Jekyll to Orgmode

[Bastien]

Hi ST,

ST <smntov@gmail.com> writes:

> Could you, please, share your website publishing workflow (considering
> the 3 issues I've mentioned)?

if people take the time to share this on the list, would you be kind
enough to take the time to enhance Worg documentation with a readable
synthesis of all answers?

If a matter of (1) creating a user on https://code.orgmode.org then
(2) cloning Worg's repository then adding/publishing your content.

Thanks a lot!

-- 
 Bastien

Re: Moving from Jekyll to Orgmode

[ST]

On Sun, 2018-04-29 at 11:07 +0200, Bastien wrote:
> Hi ST,
> 
> ST <smntov@gmail.com> writes:
> 
> > Could you, please, share your website publishing workflow (considering
> > the 3 issues I've mentioned)?
> 
> if people take the time to share this on the list, would you be kind
> enough to take the time to enhance Worg documentation with a readable
> synthesis of all answers?

English is not my mother tongue, but I'll give it a try...

Thank you!

Re: Moving from Jekyll to Orgmode

[Ista Zahn]

On Sun, Apr 29, 2018 at 4:50 AM, ST <smntov@gmail.com> wrote:
> Hi Scott,
>
> thank you, and all other responders, for the shared information. The
> reason I want to leave Jekyll is because I don't want to depend on a
> tool that relies on language (Ruby)/environment that I don't know/use
> (in this respect Hugo is the same for me). I prefer something more
> simplistic, even though if I'll have to invest some time for it to work
> initially. Those 3 features I've mentioned are almost all I need, more
> or less.
>
> Could you, please, share your website publishing workflow (considering
> the 3 issues I've mentioned)?

I use Nikola (https://getnikola.com/). It has a plugin for org source files
(https://plugins.getnikola.com/v8/orgmode/). It claims to support
multilingual sites, though I have not used that feature.

--Ista

>
> Thank you!
>
> On Sat, 2018-04-28 at 18:13 -0400, Scott Randby wrote:
>> On 04/28/2018 05:40 PM, Diego Zamboni wrote:
>> >
>> > Org-mode is not really a website-publishing tool like Jekyll, although it can be part of the chain. Org-mode at its core is a markup language, although with considerable tooling support from org-mode and related tools in Emacs.
>> >
>>
>> I think Org is a good website publishing tool in many ways. I've been using it for making and publishing my website since 2010. Sure, it has some limitations, but I think it can be made to work nicely for a lot of types of sites. But I do agree that the Org/Hugo combination is really good.
>>
>> Scott Randby
>>
>
>

Re: Moving from Jekyll to Orgmode

[Scott Randby]

On 04/29/2018 04:50 AM, ST wrote:
> Hi Scott,
> 
> thank you, and all other responders, for the shared information. The
> reason I want to leave Jekyll is because I don't want to depend on a
> tool that relies on language (Ruby)/environment that I don't know/use
> (in this respect Hugo is the same for me). I prefer something more
> simplistic, even though if I'll have to invest some time for it to work
> initially. Those 3 features I've mentioned are almost all I need, more
> or less.
> 
> Could you, please, share your website publishing workflow (considering
> the 3 issues I've mentioned)?

I'm sorry, but I can't address any of your three issues. My site is in English only, I use regular links, and my style is very simple and made so the site will work well on any device. Here is a link to it: http://srandby.org/

The Org source code isn't available yet, but it isn't anything special. The key is really the CSS which you can easily obtain.

For publishing, I update a file, use Org's HTML export facility (C-c C-e h or C-c C-e C-s h to export a subtree), and then upload to the server. Not very sophisticated, but I find it to be very efficient.

I haven't had time to look into the more complex things one can do regarding Org and websites.

Scott

Re: Moving from Jekyll to Orgmode

[Saša Janiška]

ST <smntov@gmail.com> writes:

> I would like to rewrite my website using Orgmode (till now I used
> Jekyll). It would be nice if you could help me with following questions:

I recommend you to take look at ox-hugo (https://ox-hugo.scripter.co/)


Sincerely,
Gour

-- 
As the embodied soul continuously passes, in this body,
from boyhood to youth to old age, the soul similarly passes
into another body at death. A sober person is not bewildered
by such a change.

Re: Moving from Jekyll to Orgmode

[Luis Roca]

On Sun, 2018-04-29 at 09:45 +0200, Saša Janiška wrote:
> ST <smntov@gmail.com> writes:
> 
> > I would like to rewrite my website using Orgmode (till now I used
> > Jekyll). It would be nice if you could help me with following
> > questions:
> 
> I recommend you to take look at ox-hugo (https://ox-hugo.scripter.co/
> )
> 
> 
> Sincerely,
> Gour
> 

I tested easy-hugo recently but the exporting of org files was
inconsistent with headlines and content separated. Does ox-hugo export
well consistently? 

If so I may try Hugo again.

Thanks in advance,
Luis

Re: Moving from Jekyll to Orgmode

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 3553 bytes --]

Hi Luis,

easy-hugo is simply a control layer over plain Hugo. As such, when you write a post in org format, it’s not org-mode but Hugo who is doing the interpretation, using the goorgeous library (https://github.com/chaseadamsio/goorgeous/ <https://github.com/chaseadamsio/goorgeous/>). This is why there are inconsistencies and other problems in parsing - goorgeous does not support the whole range of org-mode constructs. I originally started with easy-hugo as well, and got increasingly frustrated by some of these issues.

ox-hugo takes a different approach: it uses org-mode’s ox-markdown 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 its own native format: org-mode processes org, and Hugo processes Markdown. Thanks to this, you can even include Hugo shortcodes (https://gohugo.io/content-management/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’s doable if you want it).

Another very nice ox-hugo feature is its “One post per Org subtree” mode (https://ox-hugo.scripter.co/#screenshot-one-post-per-subtree <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 very well, and allows you to have tags/categories or other attributes per subtree, so you don’t have to repeat them on every post. If you really want to keep each post in a separate file, that is doable as well. The ox-hugo website has a lot of very useful information.

Finally, you can do the transition gradually - for my website, I had years of accumulated Markdown files from my adventures with Jekyll, Octopress and 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 converted to Markdown files, they end up alongside the old hand-crafted files, and Hugo just processes them all together.

I really recommend ox-hugo, Kaushal has done a fantastic job and he is also really helpful and responsive with questions.

Tip: I learned a lot by reading the source files for https://ox-hugo.scripter.co/ <https://ox-hugo.scripter.co/> and for https://scripter.co/ <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 <http://cf-learn.info/>) at https://ox-hugo.scripter.co/doc/examples/ <https://ox-hugo.scripter.co/doc/examples/>

Hope this helps,
—Diego

> On 29 Apr 2018, at 14:55, Luis Roca <roca@pobox.com> wrote:
> 
> On Sun, 2018-04-29 at 09:45 +0200, Saša Janiška wrote:
>> ST <smntov@gmail.com> writes:
>> 
>>> I would like to rewrite my website using Orgmode (till now I used
>>> Jekyll). It would be nice if you could help me with following
>>> questions:
>> 
>> I recommend you to take look at ox-hugo (https://ox-hugo.scripter.co/
>> )
>> 
>> 
>> Sincerely,
>> Gour
>> 
> 
> I tested easy-hugo recently but the exporting of org files was
> inconsistent with headlines and content separated. Does ox-hugo export
> well consistently? 
> 
> If so I may try Hugo again.
> 
> Thanks in advance,
> Luis
> 


[-- Attachment #2: Type: text/html, Size: 4966 bytes --]

Re: Moving from Jekyll to Orgmode

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 5923 bytes --]

Hi Diego,

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

>
> ox-hugo takes a different approach: it uses org-mode’s ox-markdown
> 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 its
> 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’s 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 “One post per Org subtree” 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 very
> well, and allows you to have tags/categories or other attributes per
> subtree, so you don’t 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-subtree-based-exports
.

I also have this little annotated diagram:
https://discourse-cdn-sjc2.com/standard12/uploads/gohugo/original/2X/8/8dd4af3e103c3a691a71356aa3f91bfe1019ebae.png


> If you really want to keep each post in a separate file, that is doable as
> well. The ox-hugo website has a lot of very useful information.
>
> Finally, you can do the transition gradually - for my website, I had years
> of accumulated Markdown files from my adventures with Jekyll, Octopress and
> 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 converted
> 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
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 9081 bytes --]

Re: Moving from Jekyll to Orgmode

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 1802 bytes --]

Hi Kaushal,

First of all, thanks for your kind words, and most of all for all your work on ox-hugo!

> 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 <https://github.com/kaushalmodi/ox-hugo/issues/126> for more info.

Agree - the ideal would be to use regular org constructs for everything, but provide enough information to translate it into the appropriate shortcodes when appropriate.

> I also have this little annotated diagram:
> https://discourse-cdn-sjc2.com/standard12/uploads/gohugo/original/2X/8/8dd4af3e103c3a691a71356aa3f91bfe1019ebae.png <https://discourse-cdn-sjc2.com/standard12/uploads/gohugo/original/2X/8/8dd4af3e103c3a691a71356aa3f91bfe1019ebae.png>

Very useful! I had seen the table but the diagram (although it takes a bit to understand) make it all very visual.

> 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") }} 

Indeed, Hugo is incredibly powerful. I’m still far from an expert on it, although I’ve started dabbling into modifying/creating my own templates. Hugo has quite a bit of a learning curve, so it’s not for everyone, but if you are willing to spend some time learning it, it’s really worth the effort.

Cheers,
—Diego


[-- Attachment #2: Type: text/html, Size: 3010 bytes --]

Re: Moving from Jekyll to Orgmode

[Thomas S. Dye]

Aloha Kaushal

Kaushal Modi writes:
>
>> 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.

This looks like an interesting project.

I've browsed the various Hugo themes and the example web sites. I 
think I've seen websites similar to and themes suitable for a 
variety of sites I'd like to consolidate: archaeology course 
syllabus and class calendar; documentation for a software project; 
a publication list with download links; and a book/article review 
blog.  I use org-mode for writing these kinds of thing now, and 
I'm hoping to work out a way to make my org mode source work with 
Hugo.

I'm especially keen on previewing the web pages as I work on them, 
which was super easy to set up (thanks!), and generating 
"responsive" content to satisfy my smartphone connected students.

I see that ox-hugo and many Hugo templates have a blog as their 
focus.  Is it reasonable to go down the ox-hugo path for my 
planned sites?  Or, is the blog focus likely to restrict what I'd 
like to do?

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: Moving from Jekyll to Orgmode

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 3178 bytes --]

Hello Thomas,

On Fri, May 4, 2018 at 2:50 AM Thomas S. Dye <tsd@tsdye.com> wrote:

> This looks like an interesting project.
>
> I've browsed the various Hugo themes and the example web sites. I
> think I've seen websites similar to and themes suitable for a
> variety of sites I'd like to consolidate: archaeology course
> syllabus and class calendar; documentation for a software project;
> a publication list with download links; and a book/article review
> blog.


That's correct, you can use Hugo to generate any of those kinds of sites. I
use it for my blog, the ox-hugo doc site itself, the bare-bones ox-hugo
test site, product doc site at work. I have also used it in the past for a
"for-rent" site in the past (and it worked ;-)).


>   I use org-mode for writing these kinds of thing now, and
> I'm hoping to work out a way to make my org mode source work with
> Hugo.
>

At minimum you just need the #+hugo_base_dir keyword and EXPORT_FILE_NAME
property (if using per-subtree flow). So it should not be too difficult. To
get an idea, I made these[1] changes to make the pre-existing use-package
Org manual ready for ox-hugo export.


> I'm especially keen on previewing the web pages as I work on them,
> which was super easy to set up (thanks!),


Great! So I gather that you were able to get a preliminary setup of
ox-hugo + Hugo working?


> and generating  "responsive" content to satisfy my smartphone connected
> students.
>

That part is not too difficult if you want to get the basic
responsiveness.. just adding the viewport meta tag in HTML head does most
of the job:

<meta name="viewport" content="width=device-width, initial-scale=1,
maximum-scale=5">

You need to get into CSS hacking if you want to go further in @media based
CSS formatting, or implementing CSS grids, etc.


> I see that ox-hugo and many Hugo templates have a blog as their
> focus.  Is it reasonable to go down the ox-hugo path for my
> planned sites?


I think so, as I mentioned earlier, I have used it for a variety of sites.
The Hugo theme tagging system is not great as it relies completely on what
the theme authors manually tag those as. But this[2] gives a small
selection of themes for documentation sites. I might find more sites that
fit your needs as you explore each of the themes on that site (don't reply
100% on tags).


>   Or, is the blog focus likely to restrict what I'd like to do?
>

Hugo Go templating is very powerful[3]. It inherently has no restrictions.
The templating language does not have a "blog focus".

If you decide to use a theme, just as is[*], then that's a restriction. I
would suggest to pick a theme that best fits your need, and then gradually
mold (mould?) it as you learn more of Go templating, to make it perfect for
you.

Thanks.

Kaushal


[1]:
https://github.com/jwiegley/use-package/commit/dede56276ce157fb55f84562b10a70978c34230e#diff-980e09e4bfed99830873c784dfb12a7a

[2]: https://themes.gohugo.io/tags/documentation/

[3]: Here are some of the professional non-blog sites created using Hugo:
https://gohugo.io/showcase/.

[*]: Being Emacs users, I doubt if the "use the theme as is" would work for
any of us ;-)
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 5171 bytes --]

Re: Moving from Jekyll to Orgmode

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 1298 bytes --]

Hello Thomas,

I forgot to expand a bit on this part..

On Fri, May 4, 2018 at 9:43 AM Kaushal Modi <kaushal.modi@gmail.com> wrote:

>
>
>>   I use org-mode for writing these kinds of thing now, and
>> I'm hoping to work out a way to make my org mode source work with
>> Hugo.
>>
>
> At minimum you just need the #+hugo_base_dir keyword and EXPORT_FILE_NAME
> property (if using per-subtree flow). So it should not be too difficult. To
> get an idea, I made these[1] changes to make the pre-existing use-package
> Org manual ready for ox-hugo export.
>

I port some of my pre-existing notes in Org format to my blog as I get
time. Here's a recent one..

Org source:
https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/raw/master/content-org/notes/awk/awk.org

The only lines added to it for exporting (using the per-file flow) using
ox-hugo were:

#+hugo_base_dir: ../../../
#+hugo_section: notes
#+hugo_bundle: awk
#+export_file_name: index

#+hugo_categories: unix
#+hugo_tags: awk

And I added this Org Special block supported by ox-hugo:

#+begin_description
Collection of ~awk~ examples.
#+end_description

With that in place, I exported the Markdown file, committed it to my repo,
Netlify ran hugo to regenerate my site, and deployed it to
https://scripter.co/notes/awk/.

-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2235 bytes --]

Re: Moving from Jekyll to Orgmode

[Thomas S. Dye]

Aloha Kaushal,

Kaushal Modi writes:

> Hello Thomas,
>
> On Fri, May 4, 2018 at 2:50 AM Thomas S. Dye <tsd@tsdye.com> 
> wrote:
>
>> This looks like an interesting project.
>>
>> I've browsed the various Hugo themes and the example web sites. 
>> I
>> think I've seen websites similar to and themes suitable for a
>> variety of sites I'd like to consolidate: archaeology course
>> syllabus and class calendar; documentation for a software 
>> project;
>> a publication list with download links; and a book/article 
>> review
>> blog.
>
>
> That's correct, you can use Hugo to generate any of those kinds 
> of sites. I
> use it for my blog, the ox-hugo doc site itself, the bare-bones 
> ox-hugo
> test site, product doc site at work. I have also used it in the 
> past for a
> "for-rent" site in the past (and it worked ;-)).
>
>
>>   I use org-mode for writing these kinds of thing now, and
>> I'm hoping to work out a way to make my org mode source work 
>> with
>> Hugo.
>>
>
> At minimum you just need the #+hugo_base_dir keyword and 
> EXPORT_FILE_NAME
> property (if using per-subtree flow). So it should not be too 
> difficult. To
> get an idea, I made these[1] changes to make the pre-existing 
> use-package
> Org manual ready for ox-hugo export.
>
>
>> I'm especially keen on previewing the web pages as I work on 
>> them,
>> which was super easy to set up (thanks!),
>
>
> Great! So I gather that you were able to get a preliminary setup 
> of
> ox-hugo + Hugo working?

Yes, your ox-hugo test site was up and running in a few minutes. 
Every few seconds new blog entries would pop up on my browser as 
Hugo processed the test file.

The hardest part for me was getting ox-hugo to work in spacemacs. 
This isn't an ox-hugo thing.  I've had problems with other org 
mode components in spacemacs, mostly having to do with the order 
things are loaded.

>
>
>> and generating  "responsive" content to satisfy my smartphone 
>> connected
>> students.
>>
>
> That part is not too difficult if you want to get the basic
> responsiveness.. just adding the viewport meta tag in HTML head 
> does most
> of the job:
>
> <meta name="viewport" content="width=device-width, 
> initial-scale=1,
> maximum-scale=5">
>
> You need to get into CSS hacking if you want to go further in 
> @media based
> CSS formatting, or implementing CSS grids, etc.
>

Apparently, there is a 'responsive' module for Hugo that several 
themes use.  I'm hoping to find responsiveness out of the box 
through careful choice of themes.

>> I see that ox-hugo and many Hugo templates have a blog as their
>> focus.  Is it reasonable to go down the ox-hugo path for my
>> planned sites?
>
>
> I think so, as I mentioned earlier, I have used it for a variety 
> of sites.
> The Hugo theme tagging system is not great as it relies 
> completely on what
> the theme authors manually tag those as. But this[2] gives a 
> small
> selection of themes for documentation sites. I might find more 
> sites that
> fit your needs as you explore each of the themes on that site 
> (don't reply
> 100% on tags).
>
>
>>   Or, is the blog focus likely to restrict what I'd like to do?
>>
>
> Hugo Go templating is very powerful[3]. It inherently has no 
> restrictions.
> The templating language does not have a "blog focus".
>
> If you decide to use a theme, just as is[*], then that's a 
> restriction. I
> would suggest to pick a theme that best fits your need, and then 
> gradually
> mold (mould?) it as you learn more of Go templating, to make it 
> perfect for
> you.

Perfect.  Thanks.  I'm looking forward to getting started with 
ox-hugo.

Many thanks for the useful links.

All the best,
Tom

> Thanks.
>
> Kaushal
>
>
> [1]:
> https://github.com/jwiegley/use-package/commit/dede56276ce157fb55f84562b10a70978c34230e#diff-980e09e4bfed99830873c784dfb12a7a
>
> [2]: https://themes.gohugo.io/tags/documentation/
>
> [3]: Here are some of the professional non-blog sites created 
> using Hugo:
> https://gohugo.io/showcase/.
>
> [*]: Being Emacs users, I doubt if the "use the theme as is" 
> would work for
> any of us ;-)


--
Thomas S. Dye
http://www.tsdye.com

Re: Moving from Jekyll to Orgmode

[Grant Rettke]

On Sat, Apr 28, 2018 at 4:05 PM, ST <smntov@gmail.com> wrote:
> 3. is there a free modern "corporate" style theme for org-mode?

Twitter Bootstrap https://github.com/marsmining/ox-twbs and
and these themes https://github.com/fniessen/org-html-themes are corporate-ish.

Re: Moving from Jekyll to Orgmode

[ST]

On Sun, 2018-04-29 at 11:45 -0500, Grant Rettke wrote:
> On Sat, Apr 28, 2018 at 4:05 PM, ST <smntov@gmail.com> wrote:
> > 3. is there a free modern "corporate" style theme for org-mode?
> 
> Twitter Bootstrap https://github.com/marsmining/ox-twbs and

This looks nice...

1. Does it mean that any Bootstrap theme can be used with this?
see here: https://themes.getbootstrap.com/

2. Does it support the latest Bootstrap 4.1?

Thank you!

Re: Moving from Jekyll to Orgmode

[Rasmus]

ST <smntov@gmail.com> writes:

> Hello,
>
> I would like to rewrite my website using Orgmode (till now I used
> Jekyll). It would be nice if you could help me with following questions:
>
> 1. could somebody, please, point me to a tutorial on how to create a
> multilingual site? Like the orgmode.org with EN:FR:JA. Ideally it would
> be if one would have page-aware language switch, i.e. if one is on the
> page orgmode.org/fr/features.html and clicks JA he will be redirected to
> orgmode.org/ja/features.html (and not .../ja/index.html as it is now)...

I don’t know how to that.  You can easily add language buttons to your
documents via :html-preamble (see org-publish-project-alist).  How to
automatically move people to the right side based on their preferences is
another thing.  I know Django supports multilingual pages, so maybe their
documentation discuss this issue on a more technical level.

> 2. how can one create "prettified" links, i.e. /features/ instead
> of /features.html ? Basically during the website generation for the file
> features.org a directory `features` needs to be created and the html
> file placed into `features/index.html` ... Is there a tutorial on how to
> do that?

You make a wrapper around org-html-publish-to-html that creates folders
and from filename and save file as index in the folder.  The wrapper
function is then used as the :publishing-function in
org-publish-project-alist.

Something like this (untested).

(lambda (plist filename pub-dir)
  (let ((dir (make-directory (file-name-as-directory (file-name-base filename))
                             pub-dir)))
    (org-latex-publish-to-html plist filename dir)
    (rename-file (concat dir (file-name-base filename) ".html")
                 (concat dir "index.html"))))


You could also move around your source files before publishing via the
:preparation-function.

> 3. is there a free modern "corporate" style theme for org-mode?

Everything has classes so it’s easy to make a style that suits you.  Just
find the color and font combinations that you like.

There’s an example of a technique I use here:

    https://gitlab.com/pages/org-mode

Rasmus

-- 
Look, it is what it is because it was what it was

Re: Moving from Jekyll to Orgmode

[ST]

> > 2. how can one create "prettified" links, i.e. /features/ instead
> > of /features.html ? Basically during the website generation for the file
> > features.org a directory `features` needs to be created and the html
> > file placed into `features/index.html` ... Is there a tutorial on how to
> > do that?
> 
> You make a wrapper around org-html-publish-to-html that creates folders
> and from filename and save file as index in the folder.  The wrapper
> function is then used as the :publishing-function in
> org-publish-project-alist.
> 
> Something like this (untested).
> 
> (lambda (plist filename pub-dir)
>   (let ((dir (make-directory (file-name-as-directory (file-name-base filename))
>                              pub-dir)))
>     (org-latex-publish-to-html plist filename dir)
>     (rename-file (concat dir (file-name-base filename) ".html")
>                  (concat dir "index.html"))))
> 
> 
> You could also move around your source files before publishing via the
> :preparation-function.

Thank you very much! Unfortunately I don't know lisp, so I have to learn
it first to understand your solution... but now I have something to
start with. I wish org html export will become a real static site
generator, like jekyll, hugo, etc..

Re: Moving from Jekyll to Orgmode

[Rasmus]

ST <smntov@gmail.com> writes:

>> > 2. how can one create "prettified" links, i.e. /features/ instead
>> > of /features.html ? Basically during the website generation for the file
>
>> > features.org a directory `features` needs to be created and the html
>> > file placed into `features/index.html` ... Is there a tutorial on how to
>> > do that?
>> 
>> You make a wrapper around org-html-publish-to-html that creates folders
>> and from filename and save file as index in the folder.  The wrapper
>> function is then used as the :publishing-function in
>> org-publish-project-alist.
>> 
>> Something like this (untested).
>> 
>> (lambda (plist filename pub-dir)
>>   (let ((dir (make-directory (file-name-as-directory (file-name-base filename))
>>                              pub-dir)))
>>     (org-latex-publish-to-html plist filename dir)
>>     (rename-file (concat dir (file-name-base filename) ".html")
>>                  (concat dir "index.html"))))
>> 
>> 
>> You could also move around your source files before publishing via the
>> :preparation-function.
>
> Thank you very much! Unfortunately I don't know lisp, so I have to learn
> it first to understand your solution... but now I have something to
> start with. I wish org html export will become a real static site
> generator, like jekyll, hugo, etc..

I *think* that is what ox-publish is, but indeed, it’s a bit hairy to set
up.

Rasmus

-- 
⠠⠵

Re: Moving from Jekyll to Orgmode

[ST]

On Tue, 2018-05-08 at 00:21 +0200, Rasmus wrote:
> ST <smntov@gmail.com> writes:
> 
> >> > 2. how can one create "prettified" links, i.e. /features/ instead
> >> > of /features.html ? Basically during the website generation for the file
> >
> >> > features.org a directory `features` needs to be created and the html
> >> > file placed into `features/index.html` ... Is there a tutorial on how to
> >> > do that?
> >> 
> >> You make a wrapper around org-html-publish-to-html that creates folders
> >> and from filename and save file as index in the folder.  The wrapper
> >> function is then used as the :publishing-function in
> >> org-publish-project-alist.
> >> 
> >> Something like this (untested).
> >> 
> >> (lambda (plist filename pub-dir)
> >>   (let ((dir (make-directory (file-name-as-directory (file-name-base filename))
> >>                              pub-dir)))
> >>     (org-latex-publish-to-html plist filename dir)
> >>     (rename-file (concat dir (file-name-base filename) ".html")
> >>                  (concat dir "index.html"))))
> >> 
> >> 
> >> You could also move around your source files before publishing via the
> >> :preparation-function.
> >
> > Thank you very much! Unfortunately I don't know lisp, so I have to learn
> > it first to understand your solution... but now I have something to
> > start with. I wish org html export will become a real static site
> > generator, like jekyll, hugo, etc..
> 
> I *think* that is what ox-publish is, but indeed, it’s a bit hairy to set
> up.

Is the difficulty to setup ox-publish the sole disadvantage vis.
ox-hugo/ox-jekyll/etc.? Is the functionality the same more_or_less?

What ox-hugo devs/users have to say on this?

Re: Moving from Jekyll to Orgmode

[Thomas S. Dye]

Aloha ST,

ST writes:
>
> Is the difficulty to setup ox-publish the sole disadvantage vis.
> ox-hugo/ox-jekyll/etc.? Is the functionality the same 
> more_or_less?
>
> What ox-hugo devs/users have to say on this?

I enjoy the hugo server.  Make a change to the org mode file, 
export with ox-hugo, and then look at the web browser to see the 
effect of the change.  It makes the work much easier, IMHO.

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: Moving from Jekyll to Orgmode

[ST]

> >
> > Is the difficulty to setup ox-publish the sole disadvantage vis.
> > ox-hugo/ox-jekyll/etc.? Is the functionality the same 
> > more_or_less?
> >
> > What ox-hugo devs/users have to say on this?
> 
> I enjoy the hugo server.  Make a change to the org mode file, 
> export with ox-hugo, and then look at the web browser to see the 
> effect of the change.  It makes the work much easier, IMHO.
> 

Jekyll also has a built-in web server. It is indeed useful. I didn't
check but I thought there must be similar standard command line Linux
tool for this, so you could immediately see the results of ox-publish
exported website. Is anybody aware of such a tool?

Re: Moving from Jekyll to Orgmode

[Diego Zamboni]

[-- Attachment #1: Type: text/plain, Size: 521 bytes --]

>
>
> Is the difficulty to setup ox-publish the sole disadvantage vis.
> ox-hugo/ox-jekyll/etc.? Is the functionality the same more_or_less?
>
> What ox-hugo devs/users have to say on this?


I have never used ox-publish, but getting started with ox-hugo is really
easy. I think the main difference might be that ox-hugo is tailored
specifically for Hugo, which influences its expected directory structure,
file output format, etc. Ox-publish might be more generic and customizable
for arbitrary output formats.

--Diego

[-- Attachment #2: Type: text/html, Size: 825 bytes --]

Re: Moving from Jekyll to Orgmode

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 1999 bytes --]

Hello,

On Wed, May 9, 2018, 3:36 AM ST <smntov@gmail.com> wrote:

>
> Is the difficulty to setup ox-publish the sole disadvantage vis.
> ox-hugo/ox-jekyll/etc.?


ox-publish is not *that* difficult to set up. Once you have it set up once,
you just reuse that with minor tweaks for different projects. The Org
manual has nice examples of simple and complex ox-publish configs; try them
out.

For me, personally, ox-publish didn't turn out to be the right tool for
blogging, especially where I want to have a single Org file to hold
multiple posts. I do use it though for applications like batch-exporting an
Org file or a directory of Org files to multiple formats.

Talking about comparing it with ox-hugo/ox-jekyll, etc... they don't
compare apples to apples.

Ox-publish is an inbuilt Org utility that works with *any* Org exporter
backend that has hooks for ox-publish (ox-hugo hasn't done that; read
further for more).

Whereas, ox-hugo is an Org exporter backend that exports to Markdown
(mostly standard Markdown + some Hugo specific syntax + bits and pieces of
HTML where necessary) + Hugo front-matter + fine-tuned "ox-publishy"
functionality.

Is the functionality the same more_or_less?
>

Again, not apples to apples..

>
Here's a coarse way to explain the function of ox-publish.. it takes the
Org files from the specified dir, exports them using an
ox-publish-supporting exporter, and puts them in some destination dir.

Ox-hugo does this:

- Exports the current Org file as a single post, or loops through subtrees
(using an interesting logic) in the current file and exports them as
individual posts. (Ox-publish does not allow exporting subtrees from a
single Org file.)
- The destination for exported Markdown files is decided based on
Hugo-specific Org keywords like HUGO_BASE_DIR, HUGO_SECTION, HUGO_BUNDLE.
Here's where ox-hugo works sort of like ox-publish.

What ox-hugo devs/users have to say on this?
>

Hope that helps clarify the differences.

Kaushal

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 3263 bytes --]