8 ms·

Shameless plug: https://ox-hugo.netlify.com https://ox-hugo.netlify.com I just announced the ox-hugo package. I love the blogging framework of Hugo, but dislik

Shameless plug: https://ox-hugo.netlify.com https://ox-hugo.netlify.com I just announced the ox-hugo package. I love the blogging framework of Hugo, but disliked that I needed to manually take care of the post front matter and also noticed the shortcomings of writing in just Markdown. I also missed the tree-based text organization of Org mode. So this package was born. Writing posts in Org mode gives you all the Org markup power (that's already more than Markdown), plus a lot more! like Org Babel, property inheritance, etc. An example: I wrote this post ( https://scripter.co/notes/string-functions-nim-vs-python/ https://scripter.co/notes/string-functions-nim-vs-python/ ) that's heavy with code blocks and results of evaluating those code blocks. It would be super-painful in Markdown to paste all the code blocks and also their results. In the Org source: https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/raw/master/content-org/notes/string-fns-nim-vs-python.org https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/raw/mas..., each of the #+RESULTS blocks in that Org source are auto generated using the Org Babel feature. I elaborate more on why I use ox-hugo, or why I use Org for blogging in native Emacs environment here: https://ox-hugo.netlify.com/doc/why-ox-hugo/ https://ox-hugo.netlify.com/doc/why-ox-hugo/ Even if one is not using Emacs as their editor, as the OP mentions, the Org markup is simple enough that anyone can use their favorite editor to write in Org. To add to that, using a little Makefile, they can run Emacs in batch mode to take advantage of true Org mode features like Org Babel, etc. For instance, one can clone the ox-hugo repo, https://github.com/kaushalmodi/ox-hugo/ https://github.com/kaushalmodi/ox-hugo/, and just run "make test" or "make doc" to let ox-hugo do its thing, without having anyone to know what to do after opening Emacs, what command to run, etc. "make doc" will generate all the Markdown content needed for the entire documentation website that I linked in the very beginning of this comment, all from a single Org file.. You cannot do that in Markdown.

bastijn 9y ago
Call it blasphemy but in my opinion the markdown is easier to read than the orgmode in your examples. Especially when you think away your syntax highlighting. Markdown is not just for short notation over html, it is also for readability of plain text. I'd argue it's better suited at that, especially to the untrained, than orgmode. I use markdown in my organization because even non-technical people can write and read it easily and without top much eyestrain (and we convert it to websites and pdf for official release). I also disagree with the original post to the extent that it is correct but attacks issues that are not there in practice. Yes, there are multiple versions but this is not a major issue. Most people use github flavored anyway. There is an initiative to standardize markdown by the way [0]. The fact that it is not really taken up tells me there is no big issue with having multiple markdown flavors. [0] http://commonmark.org/ http://commonmark.org/
- kaushalmodi 9y ago
  There's a big difference between seeing an Org file in raw vs in an editor. This is how I see it: https://ox-hugo.netlify.com/images/ox-hugo-doc-source-viewing-in-Termux-Android.png https://ox-hugo.netlify.com/images/ox-hugo-doc-source-viewin... Also, I prefer not leaving empty blank lines in between. Factors like that can change one's perception of readability.
  - bastijn 9y ago
    The problem is that while I do know my setup, I can't trust that of my colleagues. You'd be surprised how many engineers even run without proper tooling. I.e. Are used to things like bare UltraEdit or Notepad++ for editing these kind of files. Especially the older generations (no offense). In addition, I have non-technical people who only use notepad to update the files. Also, your markup without the blank lines and the fact that headings look like bullets to me make it harder to follow.
    - kaushalmodi 9y ago
      > your markup without the blank lines and That's because I like that and only I am using that. If it's a matter of team collaboration, certain ground rules can be set to resolve that.. like use blank lines after headings. You might be surprised but there's actually an Org mode setting in Emacs which can be configured to set how many blank lines to auto-insert after each heading -- I set that to zero. > the fact that headings look like bullets to me make it harder to follow. If you start using Org, it won't look like that. In fact, I use hyphens for list items in Markdown too as they work there too, so there is not too much context switching as I switch between Org and Markdown. I went through a lot of that as I was developing the ox-hugo package :) Also in Org, lines starting with "# " are comments, which intuitively are comments in many languages. Markdown doesn't have comment syntax! I need to do stuff like below to fake a comment in Markdown: [//]: # "comment" So the "headings look like bullets issue" will wear off once you start using Org, and then you wish Markdown also did the same :)
      - 9y ago
alanbernstein 9y ago
Cool, I've been looking for exactly this tool.
- kaushalmodi 9y ago
  Thank you. Please try it out and open as many issues as you can. I'd like "ox-hugo" to just work for others as it has for me.
projectant 9y ago
I think org-mode is good. But I think that it and markdown could have better syntax for links. Like a link doesn't have to be wrapped in an opener or closer, since any spaces can be escaped. So you could simply do: ~A new search engine@https://google.com https://google.com I think considering the status of @ in the rfc this can be parsed. If a link has spaces just replace them with + or %20
- simonh 9y ago
  A main goal of Markdown is to be easy for anyone to use. Having to substitute characters in a URL string might be fairly trivial for you or me, but certainly not for everybody.
  - projectant 9y ago
    It's a trade off definitely. The way I think of it is, how often would you have to sub? Rarely. Since most uris do not have spaces, and even putting a URL in an address bar will usually sub it. On the plus side, having a simpler syntax for URLs I feel is more readable which is great for ease of use. I think ~ looks like a link, and @ makes sense semantically. But to be sure I think the legacy syntax could remain as a fallback / alternative. New syntax is something that could be tried in a flavor.
jhoechtl 9y ago
It's worth noting that Hugo now has native org mode support https://discourse.gohugo.io/t/org-mode-content-support-merged-into-hugo-master/5530 https://discourse.gohugo.io/t/org-mode-content-support-merge...
- kaushalmodi 9y ago
  Of course I am aware of that :) I did my "market study" before I started investing time for this project. I have a page on ox-hugo Documentation site (the first link in my original comment) that talks in detail why I needed to have a ox-hugo: https://ox-hugo.netlify.com/doc/why-ox-hugo/ https://ox-hugo.netlify.com/doc/why-ox-hugo/
wodenokoto 9y ago
For people who don't find writing in native emacs a bonus, such posts are very straight forward to write in jupyther notebook. It even one up most other editors code highlight by rendering markdowns blocks inline.

bastijn 9y ago

Call it blasphemy but in my opinion the markdown is easier to read than the orgmode in your examples. Especially when you think away your syntax highlighting. Markdown is not just for short notation over html, it is also for readability of plain text. I'd argue it's better suited at that, especially to the untrained, than orgmode. I use markdown in my organization because even non-technical people can write and read it easily and without top much eyestrain (and we convert it to websites and pdf for official release). I also disagree with the original post to the extent that it is correct but attacks issues that are not there in practice. Yes, there are multiple versions but this is not a major issue. Most people use github flavored anyway. There is an initiative to standardize markdown by the way [0]. The fact that it is not really taken up tells me there is no big issue with having multiple markdown flavors. [0] http://commonmark.org/ http://commonmark.org/

kaushalmodi 9y ago
There's a big difference between seeing an Org file in raw vs in an editor. This is how I see it: https://ox-hugo.netlify.com/images/ox-hugo-doc-source-viewing-in-Termux-Android.png https://ox-hugo.netlify.com/images/ox-hugo-doc-source-viewin... Also, I prefer not leaving empty blank lines in between. Factors like that can change one's perception of readability.
- bastijn 9y ago
  The problem is that while I do know my setup, I can't trust that of my colleagues. You'd be surprised how many engineers even run without proper tooling. I.e. Are used to things like bare UltraEdit or Notepad++ for editing these kind of files. Especially the older generations (no offense). In addition, I have non-technical people who only use notepad to update the files. Also, your markup without the blank lines and the fact that headings look like bullets to me make it harder to follow.
  - kaushalmodi 9y ago
    > your markup without the blank lines and That's because I like that and only I am using that. If it's a matter of team collaboration, certain ground rules can be set to resolve that.. like use blank lines after headings. You might be surprised but there's actually an Org mode setting in Emacs which can be configured to set how many blank lines to auto-insert after each heading -- I set that to zero. > the fact that headings look like bullets to me make it harder to follow. If you start using Org, it won't look like that. In fact, I use hyphens for list items in Markdown too as they work there too, so there is not too much context switching as I switch between Org and Markdown. I went through a lot of that as I was developing the ox-hugo package :) Also in Org, lines starting with "# " are comments, which intuitively are comments in many languages. Markdown doesn't have comment syntax! I need to do stuff like below to fake a comment in Markdown: [//]: # "comment" So the "headings look like bullets issue" will wear off once you start using Org, and then you wish Markdown also did the same :)
    - 9y ago

alanbernstein 9y ago

Cool, I've been looking for exactly this tool.

kaushalmodi 9y ago
Thank you. Please try it out and open as many issues as you can. I'd like "ox-hugo" to just work for others as it has for me.

projectant 9y ago

I think org-mode is good. But I think that it and markdown could have better syntax for links. Like a link doesn't have to be wrapped in an opener or closer, since any spaces can be escaped. So you could simply do: ~A new search engine@https://google.com https://google.com I think considering the status of @ in the rfc this can be parsed. If a link has spaces just replace them with + or %20

simonh 9y ago
A main goal of Markdown is to be easy for anyone to use. Having to substitute characters in a URL string might be fairly trivial for you or me, but certainly not for everybody.
- projectant 9y ago
  It's a trade off definitely. The way I think of it is, how often would you have to sub? Rarely. Since most uris do not have spaces, and even putting a URL in an address bar will usually sub it. On the plus side, having a simpler syntax for URLs I feel is more readable which is great for ease of use. I think ~ looks like a link, and @ makes sense semantically. But to be sure I think the legacy syntax could remain as a fallback / alternative. New syntax is something that could be tried in a flavor.

jhoechtl 9y ago

It's worth noting that Hugo now has native org mode support https://discourse.gohugo.io/t/org-mode-content-support-merged-into-hugo-master/5530 https://discourse.gohugo.io/t/org-mode-content-support-merge...

kaushalmodi 9y ago
Of course I am aware of that :) I did my "market study" before I started investing time for this project. I have a page on ox-hugo Documentation site (the first link in my original comment) that talks in detail why I needed to have a ox-hugo: https://ox-hugo.netlify.com/doc/why-ox-hugo/ https://ox-hugo.netlify.com/doc/why-ox-hugo/

wodenokoto 9y ago

For people who don't find writing in native emacs a bonus, such posts are very straight forward to write in jupyther notebook. It even one up most other editors code highlight by rendering markdowns blocks inline.