Jun 23, 2018 - New blog test

Comments

New blog test title

Delete this after publish, test only

May 18, 2017 - Blog in Org2jekyll - 4. Workflow of writing a blog post

Comments

1 Blog in Org2jekyll - 4. Workflow of writing a blog post

This post is part 4 of a short series about writing in org mode, using org2jekyll.

TL;DR: If you do not want to read this, go to 1.1

This part 4 describes next steps after configuring the stack for blogging in Jekyll and emacs org mode, as described in the software configuration step of this series. As a brief repeat from the previous part 3, we need the following to configure the blog stack:

  • Setup Github pages and it's local repo (for example, in directory BLOG=~/mzimmerm.github.io).
  • Setup Jekyll and a theme.
  • Setup org2jekyll in emacs.
  • Configure Org2jekyll directories and in init.el.

Once the setup is finished, the steps below represent a typical workflow of creating a new blog post in the above stack.

  1. M-x: org2jekyll-create-draft - Creates an empty post in org format, with today's date. Assuming the Org2jekyll directories were configured, emacs knows where to place the post we are creating - so this can run from any buffer in emacs. The command asks a series of questions, for values, required answers are:

    • layout: (post | default) - select post.
    • title: We enter the name of our post. This will end up the title, displayed on top of post. e.g. Test Blog, and also the file name of the post (mangled a bit - I do not use dots and weird characters, as the title is converted to file name, spaces replaced with dashes.)
    • Tags: We enter same values as category for now.
    • Category: We enter space separated list of categories. we can use the same for category and tag. I am not sure what is the difference.

    The end result of this step is a new file $BLOG/org/a-test-blog.org and a buffer with it's content, like this

    #+STARTUP: showall
    #+STARTUP: hidestars
    #+OPTIONS: H:2 num:nil tags:nil toc:nil timestamps:t
    #+LAYOUT: post
    #+AUTHOR: mzimmerm
    #+DATE: 2017-05-18 Thu 22:14
    #+TITLE: A Test Blog
    #+DESCRIPTION: A Test Blog
    #+TAGS: org_mode,blog,org2jekyll
    #+CATEGORIES: org_mode,blog,org2jekyll
    #+COMMENTS: true
    
  2. Write the post in org mode.. We write the blog text in the $BLOG/org/a-test-blog.org opened above. Continue with steps below when the blog is ready.
  3. M-x: org2jekyll-publish - org-exports the post from steps 1 and 2 to html by calling the "org emacs export". This command does a few things:
    • Exports the org contents to html.
    • Places the exported html to the _posts directory from which Jekyll will build and serve the post.
    • Prefixes the blog file name with date, and replaces the .org extension with the .html extension.
    • Result of this step is a file $BLOG/_posts/2017-03-18-a-test-blog.html.
  4. cd $BLOG; jekyll build - (Optional) Performs the Jekyll steps to build the "Jekyll published" blog. This step is optional, but we will likely want to do it, to test locally before pushing to github.
    • A simplified description of the this command: Jekyll performs a series of transforms, e.g. surrounds the contents of the file _posts/2017-03-18-a-test-blog.html with header and footer, and places the result in the _site directory.
    • Result of this step is a file $BLOG/_site/2017/03/a-test-blog.html.
  5. cd $BLOG; jekyll serve --baseurl=''; (Optional) Starts the Jekyll server - we use this to test the blog locally before pushing on github.
  6. Test our blog locally by browsing to http://127.0.0.1:4000/. To change a post, edit the org file and re-publish by running steps 4 and 5.
  7. cd $BLOG; git commit; git push - Pushes and published the post to Github.
    • The server on github builds and serves the pushed post, similarly what is described in steps 4 and 5, and makes the post available publicly.

Notes:

  • Simplified workflow - skipping the jekyll build: Jekyll's default watch settings is to pick up and rebuild changed files. Instead of steps 2,3,4,5,6, we can run a simpler steps, in the order 5, 2, 6. See
    • Run jekyll serve --baseurl='' (described in step 5)
    • Edit the post's org file (described in step 2)
    • M-x: org2jekyll-publish. This will publish the org as html to Jekyll's _posts, where Jekyll will pick it up and "Jekyll build and publish to _site".
    • Reload the post in the browser (described in step 6)
  • Re-Publishing a changed post: If we make a change to an older blog, the steps are the same, except that step 1 is skipped. The blog's date will not change.
  • Publishing all changed posts instead of publishing the "currently edited" post: In step 3, we can use M-x: org2jekyll-publish-posts instead of M-x: org2jekyll-publish. The former plural version publishes all changed posts. Org2jekyll will figure out all posts in the org directory which changed, and publish or re-publish them all. Then, Jekyll's build/serve will pick them up and update them.

1.1 Conclusion

Assuming our Jekyll is configured the serve settings to "watch" (to pick up and rebuild changed files), this 6-step workflow of creating and publishing a post all the way to github.io:

  1. $ jekyll serve --baseurl='' (a shell command, step 5 in text)
  2. M-x: org2jekyll-create-draft (an emacs command, step 1 in text) - creates the empty post, with today's date, e.g. $BLOG/org/a-test-blog.org.
  3. Edit the post content in org mode.
  4. M-x: org2jekyll-publish (an emacs command, step 3 in text)- org-exports the blog from the org directory to html and places it to the _posts directory. Also, the Jekyll auto-watch will build the final blog file and place it to _site directory.
  5. Test the post on http://127.0.0.1:4000/. Go back to step 3 to re-edit.
  6. $ git commit; git push - pushes the post to Github. The server there builds and serves our post, and makes it available for readers.

Apr 26, 2017 - Blog in Org2Jekyll - 3. About the Jekyll theme used in this blog

Comments

1 Blog in Org2jekyll - 3. About the Jekyll theme used in this blog

This post is part 3 of a short series about writing in org mode using org2jekyll.

The Jekyll theme on this page is slightly modified from the original jekyll clean theme. If you like the theme, you can use it from this blog, or from the original site https://github.com/scotte/jekyll-clean

The theme (optionally) uses Disqus for comments and (optionally) includes Google Analytics. Both are off by default, and can be changed in config.yml

To use this theme for a blog, look at the Jekyll docs and the original site https://github.com/scotte/jekyll-clean. Here are a few notes about about which files can be kept, modified, or removed for a reuse.

  • You can generally keep the following directories and .html files. They are mostly Liquid language sections (Liquid templates), linked from the front page or used to build pages and posts (from files in the _layouts directory).
    • Files to keep or modify:
      • index.html is the blog "front page". keep this file as it is the Liquid template that builds the front page by querying what blogs are out there.
      • about.html
      • archive.html
      • links.html
    • Directories and contents to keep or modify:
      • _layouts
        • contains files such as post.html and page.html. These files define the top level structure of your blog pages or web sites. If you create a org file named org/a-test-blog.org and give it #+LAYOUT: post, then the result post is created from post.html , substituting { { content } } tag in the post.html with _posts/a-test-blog.html ( _posts/a-test-blog.html is first created by org2jekyll-publish-posts from the org file with same name). In the process, Jekyll transforms and injects files from the _includes directory, if so directed by the layout file post.html.
      • _includes
        • is the directory where all files mentioned in include tag markup should be located - files used in includes such as { % include included-file.html % } (with the space before / after the percentage removed; jekyll refuses publish a valid include markup)
      • images todo
      • js todo
      • LICENSE
  • For making your own blog, you may want to generally remove content of the following directories on the top level, but keep the directory nodes:
    • org
      • directory where you write your posts and pages in org format (manually, or supported by org2jekyll-create-draft)
    • _posts
      • is a directory with:
        • .html files exported from .org files by command org2jekyll-publish-pages
        • Also, if you want to write your posts in markdown, you write them here as .md
    • _site
      • is a directory with .html files created by jekyll build. Files here are built by jekyll build from the following files
        • .html files and md files on the top level (e.g. index.html Liquid template file on top level is converted to _site/index.html which contains only html markup)
        • .org files from the org directory

Hopefully this is of some use in starting to use a jekyll theme.