• Stars
    star
    376
  • Rank 113,810 (Top 3 %)
  • Language
    Python
  • License
    GNU General Publi...
  • Created about 11 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Blogging with Org-mode for very lazy people

## -*- coding: utf-8;mode: org; -*- ## This file is best viewed with GNU Emacs Org-mode: http://orgmode.org/

«A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.» (Antoine de Saint-Exupéry)

lazyblorg – blogging with Org-mode for very lazy people

This is a web log (blog) environment for GNU Emacs with Org-mode which generates static HTML5 web pages. It is much more superior to any other Org-mode-to-blog-solution I have seen so far!

<(All?) your Org-mode files>  --lazyblorg-->  static HTML pages
                                                      |
                                                      v
                                 optional upload (shell) script
                                                      |
                                                      v
                                                 your web space

There is a list of similar/alternative Org-mode blogging projects whose workflows seem really tedious to me.

See my original post to the Org-mode ML for how this idea of lazyblorg started in 2011.

This awesome piece of software is a sheer beauty with regard to:

  • simplicity of creating a new blog entry
    • I mean it: there is no step which can be skipped!
      • add heading+content anywhere, add ID, tag, invoke lazyblorg
  • integration into my personal, published workflows
    • here, you have to either adapt my totally awesome workflows or you have to find alternative ways of doing following things:
      • linking/including image files or attachments in general (I use this Memacs module)
        • advantage of my method: I simply add an image file by typing tsfile:2014-03-03-this-is-my-file-name.jpg in double-brackets and I really don’t care in which folder the file is currently located on my system
      • copying resulting HTML files to web-space (I do it using unison/rsync)
      • probably more to come

DISCLAIMER: This is a personal project

I wrote lazyblorg to get a blogging system that works for me exactly the way I need it. I did not write lazyblorg for the pleasure on the coding process - I just wanted to get the resulting thing working in order to be able to blog the way I want to blog.

Therefore, it’s mostly a works-for-me project. I won’t add anything that I don’t use myself.

For the same reason, I won’t accept pull requests for things like:

  • Features I don’t use myself.
  • Added complexity I don’t want.
  • Features or dependencies I don’t understand completely.
  • Stuff that might interfere with the way I’m using lazyblorg.

If you do want to adapt lazyblorg and implement your own features that conflict with the things listed above, I’d like to see you creating a fork of this project. If you drop me a line with a description how your fork differs from the original, I’m glad to add it to this README file.

If you think that your idea might be also a good one for me, you can always hand in a pull request and I’ll have a look if I’m willing to add it. However, don’t be disappointed if I don’t. I want to keep the time spent on lazyblorg at a minimum. My personal priority is visible in the lazyblorg issues where I introduced tags for high and low priority things to implement.

Target group

Lazy users of Org-mode who want to do blogging very easily and totally cool.

Or simply wannabes. I’m perfectly fine with this as long as they use lazyblorg.

Other people using lazyblorg

Pages using lazyblorg are listed on my personal tag page on “lazyblorg”. Please do drop me a line when you want to get your page added to the list.

Quote from Sepp Jansen:

[…]

But when I revisited lazyblorg after studying the other packages, it suddenly seemed like a better solution. After only a short time of reading I figured out the entire templating and post generation system. Although not the most elegant, it is super simple and easy to understand. And those are my most important points.

The developer states that it is easy to configure and start building, and is absolutely right.

In just a few hours I went from installing dependencies to having a fully working website, including some layout and CSS customization. The included HTML and CSS is easy to modify so I could (lazily) make the site look like I wanted it to without too much digging in many little files. I even managed to make it look a lot like my old site without too much effort! Lazyblorg really lives up to its name!

[…]

I really like lazyblorg, and I’ll happily manage this website with it for as long as possible.

Skills necessary

  • modifying configuration settings, e.g., in script files
  • optional: creating scheduled tasks (cronjob, …) if you are a really lazy one (and if you trust lazyblorg to do its job in the background)

System requirements

lazyblorg is written in Python 3.

Development platform is Debian GNU/Linux. So with any decent GNU/Linux you should be fine.

It might work on OS X but I never tried it so far.

I definitely does not work with Microsoft Windows. Although a programmer can add a couple of os.path.thisorthat() here and there and it should be good to go. Please consider sending a pull-request if you are fixing this issue. Thanks!

Version and Changelog

Currently (2019-10-23), I consider lazyblorg in beta-status with version 0.96 or so.

I don’t maintain a specific changelog. However, when there are substantial changes to lazyblorg, you will find a blog article tagged with “lazyblorg”. Use an RSS/Atom aggregator to follow the blog.

Why lazyblorg?

Minimum effort for blogging.

And: your blog entries can be written anywhere in your Org-mode files. They will be found by lazyblorg. :-)

Further advantages are listed below.

Example workflow for creating a blog entry

  1. write a blog entry anywhere in your Org-mode files
    • With lazyblorg, you can, e.g., write a blog article about an event as a sub-heading of the event itself!
  2. tag your entry with :blog:
  3. add an unique ID in the PROPERTIES drawer
  4. set the state of your entry to DONE
    • make sure that a :LOGBOOK: drawer entry will be created that contains the time-stamp

An example blog entry looks like this:

** DONE An Example Blog Post           :blog:lazyblorg:software:
CLOSED: [2017-06-18 Sun 00:16]
:PROPERTIES:
:ID: 2017-07-17-example-posting
:CREATED:  [2017-06-17 Sat 23:45]
:END:
:LOGBOOK:
- State "DONE"       from "NEXT"       [2017-06-18 Sun 00:16]
:END:
       […]
Today, I found out that…

That’s it. lazyblorg does the rest. It feels like magic, doesn’t it? :-)

Advantages

These things make a blogger a happy one:

No other Org-mode blogging system I know of is able to process blog entries which are scattered across all your Org-mode documents except the usual org-export-based approaches.

No other Org-mode blogging system I know of is able to generate a blog entry with that minimum effort to the author.

You do not need to maintain a specific Org-mode file that contains you blog posts only. *Create* blog posts anywhere in between your notes, todos, contacts, …

And there are some technological advantages you might consider as well:

  • You don’t need to write or correct HTML code by yourself.
  • produces static, state-of-the-art HTML5
    • it’s super-fast on delivery to browsers
    • very low computing requirements on your web server: minimum of server load
  • No in-between format or tool.
    • Direct conversion from Org-mode to HTML/CSS.
    • dependencies have the tendency to cause problems when the dependent tools change over time
    • lazyblorg should be running fine for a long time after it is set up properly
  • Decide by yourself how and where you are hosting your blog files and log files.
  • you will find more advantages when running and using lazyblorg - I am very confident about that ;-)

Disadvantages

Yes, there are some disadvantages. I am totally honest with you since we are becoming close friends right now:

  • lazyblorg re-generates the complete set of output pages on every run
    • this will probably changed in a future release (to me: no high priority)
    • most of the time this is not an issue at all
      • if pages are generated on a different system as the web server runs on, performance is a minor issue
      • if you don’t have thousands of pages, this will not take long
  • lazyblorg is implemented in Python:
    • Its Org-mode parser supports only a (large) sub-set of Org-mode syntax and features.
      • Basic rule: use an empty line between two different syntax elements such as paragraphs, lists, tables, and so on.
      • Whenever I think that an additional Org-mode syntax element is needed for my blog, I start thinking of implementing it
      • I am using Pandoc as a fall-back for all other Org-mode syntax elements which works pretty fine
      • For a list of general Org-mode parsers please read this page
  • lazyblorg is using state-of-the art HTML5 and CSS3
    • No old HTML4.01 transitional stuff or similar
    • Results might not be compatible with browsers such as Internet Explorer or mobile devices.
      • tell your Internet Explorer friends that they should do themselves a favor and switch to a real browser
  • You have to accept the one-time setup effort which requires knowledge of:
    • using command-line tools
    • modifying configuration files
    • summary: getting this beautiful thing to work in your environment

Features

«Technology develops from the primitive via the complex to the simple.»

(Antoine de Saint-Exupéry; note: lazyblorg is currently “primitive” but with a great outlook up to the status of being simple)

Here is a selection of features of lazyblorg which helps you to blog efficiently:

  • Converts Org-mode To HTML5: lazyblorg supports a (large sub-)set of syntax elements of Org-mode
    • also see FAQs for “What Org-mode elements are supported by lazyblorg?”
  • Different page types allow you to create:
    1. articles related to a specific date (temporal pages)
      • Those articles are published and hardly updated.
    2. articles not related to a specific date (persistent pages)
      • Frequent updates or the absence of any day-relation makes this page type very sexy to use.
    3. articles describing a tag you are using (tag pages)
      • Yes, with lazyblorg, you are (optionally) able to explain how you are using a certain tag. You can link your most important tag-related articles and so forth. Most systems don’t offer any possibility to communicate the meaning of the tags used.
    4. the entry page of your blog
      • You gotta give them a starting page ;-)
    5. the templates which are used to generate your blog pages
      • Hooray, you are able to define all templates of your blog within Org-mode as well. No need to edit source code here. Isn’t this great?
  • To efficiently notify users of new articles or changes to existing articles, lazyblorg generates RSS/ATOM feeds.
  • Really fast to use linking to other blog articles using their ID property.
  • At the bottom of each article, there is a list of related articles that back-link to here.
  • You can very easily embed image files with automatically scaling to their desired width
    • This feature is hardened against image file renaming and broken links because of moving images files to different folders
    • Users of Memacs do have advanced possibilities here as well
    • An optional image cache directory holds previously resized image file and therefore prevents resizing effort for each run.
  • For navigating through the blog articles I do recommend using the tags. Articles related to one topic share common tags whereas a date-oriented archive has only very limited use. The tag cloud which is on the tag overview page offers a quick overview of your most used tags.
  • There is a search feature which brings you to the content by searching for keywords or phrases.
  • Easy embedding of external content such as Tweets or YouTube videos.
  • You can exclude content from being published with various features:
    1. Comment lines
    2. Mark an article/heading as hidden using the tag NOEXPORT
    3. The hidden tag does publish an article but hides it from the entry page, navigational pages, and the feeds. This way, you can publish pages who can only be access by people knowing its URL.
  • Reading time estimations (multi-language) following this feature request

FAQs

See https://github.com/novoid/lazyblorg/wiki/FAQs

Installing and Starting with lazyblorg

I am using it for my own blog and therefore it gets more and more ready to use as I add new features.

What’s working so far:

External dependencies

The number of external dependencies is kept at a minimum.

This is a list of the most important dependencies:

  • Werkzeug
    • for sanitizing path components
    • I installed it on Debian GNU/Linux with sudo apt-get install python3-werkzeug
  • pickle
    • object serialization
    • most likely: should be part of your Python distribution
  • pypandoc
    • some Org-mode syntax elements are being converted using Pandoc and its Python binding pypandoc
    • you can get it via sudo apt-get install pandoc and sudo pip install python3-pypandoc
    • Note: Debian GNU/Linux 8 (Jessie) comes with a Pandoc version which is has bugs. Please install a more recent version. I upgraded to pandoc-1.15.1-1-amd64.deb from: http://pandoc.org/installing.html
  • opencv-python
    • lazyblorg scales embedded images according to the HTML export attributes
    • Install using sudo apt-get install python3-opencv
  • Sass (optional) if you want to generate your CSS from the scss-file
  • orgformat
    • This is my library that provides basic utility functions when working with Org mode strings

All other libraries should be part of a standard Python distribution.

If you don’t want to install the dependencies via package management, you can use the python way from requirements.txt:

pip install -r requirements.txt

Running tests also requires `pytest`.

How to Start

  1. Get the source
  2. Adapt config.py to meet your settings.
  3. Do a technological test-drive
    • start: lazyblorg/example_invocation.sh
    • this should work with GNU/Linux (and most probably OS X)
    • if not, there is something wrong with the set-up; maybe missing external libraries, wrong paths, …
  4. Study, understand, and adopt the content of example_invocation.sh
    • with this, you are able to modify command line parameters to meet your requirements
    • if unsure, ask for help using lazyblorg.py --help
  5. Get yourself an overview on what defines a lazyblorg blog post and write your own blog posts. A (normal temporal) blog article consists of:
    1. A (direct) tag has to be blog
      • Sorry, no tag inheritance. Every blog entry has to be explicitly tagged.
    2. You have to add an unique :ID: property
    3. The entry has to be marked with DONE
    4. A :LOGBOOK: entry has to be found with the time-stamp of setting the entry to DONE
      • in my set-up, this is created automatically
    5. Get yourself familiar on the sub-set of Org-mode syntax you can use with lazyblorg
      • Always put an empty line between different syntax elements such as a heading and the next paragraph, normal text and a list or a table, and so forth.
      • You should not get a disaster if you are using elements lazyblorg is not optimized for. The result might disappoint you, that’s all.
      • However, “unknown” Org-mode elements are automatically converted through pandoc as a fall-back.
  6. OPTIONAL: Write your own CSS file
  7. OPTIONAL: Adopt the blog template
  8. OPTIONAL: Create tag pages for your most important tags where you describe how you are using this tag, what are the most important blog entries related to the tag and so forth.
  9. Publish your pages on a web space of your choice
    • publishing can be done in various ways. This is how I do it using lazyblorg/make_and_publish_public_voit.sh which is an adopted version of lazyblorg/example_invocation.sh:
      1. invoking start_all_tests.sh
        • this is for checking whether or not recent code changes did something harmful to my (unfortunately very limited) set of unit tests
      2. invoking lazyblorg with my more or less fixed set of command line parameters
      3. invoking rsync -av testdata/2del/blog/* $HOME/public_html/
        • it synchronizes the newly generated blog data to the local copy of my web space data
        • this separation makes sense to me because with this, I am able to do test drives without overwriting my (local copy of my) blog
      4. invoking unison
        • in order to transfer my local copy of my web space data to my public web space
    • This method has the advantage that generating (invoking lazyblorg) and publishing (invoking unison) are separate steps. This way, I can locally re-generate the blog (for testing purposes) as often I want to. However, as long as I do not sync it to my web space, I keep the meta-data (which is in the local web space copy) of the published version (and not the meta-data of the previous test-run).
  10. Have fun with a pretty neat method to generate your blog pages

Because we are already close friends now, I tell you a hidden feature of lazyblorg nobody knows yet: whenever you see a π-symbol in the upper right corner of a blog entry on my blog: this is a link to the original Org-mode source of that page. This way, you can compare Org-mode-source and HTML-result right away. Isn’t that cool? :-)

Five categories of page type

There are five different types of pages in lazyblorg. Most of the time, you are going to produce temporal pages. However, it is important to understand the other ones as well.

In order to process a blog-heading to its HTML5 representation, its Org-mode file has to be included in the --orgfiles command line argument of lazyblorg.py. Do not forget to include the archive files as well.

  1. temporal
  2. persistent
  3. tags
  4. entry page
  5. templates

Please do read https://github.com/novoid/lazyblorg/wiki/Page-Types for important details.

BONUS: Preview Blog Article

It is tedious to re-generate the whole blog and even upload it to your web-space just to check the HTML version of the article you are currently writing.

Yeah, this also sucks at my side.

Good news everybody: There is a simple method to preview the article under the cursor. The script preview_blogentry.sh contains an ELISP function that extracts the current blog article (all lazyblorg criteria has to be fulfilled: ID, blog tag, status DONE), stores it into a temporary file, and invokes lazyblorg via preview_blogentry.sh with this temporary file and the Org-mode file containing the format definitions.

If this worked out, your browser shows you all generated blog articles.

Please do adopt the mentioned scripts to you specific requirements - the ones from the repository are for my personal set-up which is unlikely to fit yours (directory paths mostly).

Bang! Another damn cool feature of lazyblorg. This is going better and better. :-)

BONUS: Jump From URL to Blog Article

Imagine, you’re looking at a blog article of your nice lazyblorg-generated blog. Now you want to go to the corresponding Org-mode source to fix a typo.

The issue here is, that you have to either know, where your heading is located or you have to go to the HTML page source, extract the ID, and jump to this ID.

I’ve got a better method: put the URL of your blog article into your clipboard (via C-l C-c), press a magic shortcut in Emacs, and BAAAM! you’re right on spot.

How’s that magic happening?

Just use the following Emacs lisp code snippet, adapt the domain string, and assign a keyboard shortcut:

(defun my-jump-to-lazyblorg-heading-according-to-URL-in-clipboard ()
  "Retrieves an URL from the clipboard, gets its Org-mode source,
   extracts the ID of the article and jumps to its Org-mode heading"
  (interactive)
  (let (
        ;; Getting URL from the clipboard. Since it may contain
        ;; some text properties we are using substring-no-properties
        ;; function
        (url (substring-no-properties (current-kill 0)))
        ;; This is a check string: if the URL in the clipboard
        ;; doesn't start with this, an error message is shown
        (domain "http://karl-voit.at")
  )
    ;; Check if URL string is from my domain (all other strings do
    ;; not make any sense here)
    (if (string-prefix-p (upcase domain) (upcase url))
    ;; Retrieving content by URL into new buffer asynchronously
    (url-retrieve url
                      ;; call this lambda function when URL content is retrieved
          (lambda (status)
             ;; Extrating and preparing the ID
             (let* (
                                ;; Limit the ID search to the top 1000 characters of the buffer
                (pageheader (buffer-substring 1 1000))
                ;; Start index of the id
                                (start (string-match "<meta name=\"orgmode-id\" content=\"" pageheader))
                                ;; End index of the id
                                (end (string-match "\" />" pageheader start))
                                ;; Amount of characters to skip for the openning tag
                                (chars-to-skip (length "<meta name=\"orgmode-id\" content=\""))
                                ;; Extract ID
                                (lazyblorg-id (if (and start end (< start end))
                                                  ;; ... extract it and return.
                                                  (substring pageheader (+ start chars-to-skip) end)
                                                nil))
                                )
               (message (concat "Looking for id:" lazyblorg-id " ..."))
               (org-open-link-from-string (concat "id:" lazyblorg-id))
               )
             )
          )
  (message (concat "Sorry: the URL \"" (substring url 0 (length domain)) "...\" doesn't start with \"" domain "\". Aborting."))
  )
    )
  )

BONUS: Embedding External Things

  • Do read the Wiki for embedding external stuff like Tweets or YouTube videos.

Using relative URLs instead of domain-URLs

The links to the CSS & co, even on the homepage, start with a slash which means you can’t easily have a look at the HTML locally by opening the files, you need to spin up a webserver.

If you want to learn how to move to a more flexible setup, read this comment and follow its instructions.

How to Thank Me

I’m glad you like my tools. If you want to support me:

  • Send old-fashioned postcard per snailmail - I love personal feedback!
  • Send feature wishes or improvements as an issue on GitHub
  • Create issues on GitHub for bugs
  • Contribute merge requests for bug fixes
  • Check out my other cool projects on GitHub

If you want to contribute to this cool project, please fork and contribute!

Issues, bugs,… are maintained in the GitHub issue tracker.

I am using Python PEP8 and some ideas from Test Driven Development (TDD).

Local Variables

http://karl-voit.at/temp/github/2017-06-04_lazyblorg_README.png

More Repositories

1

Memacs

What did I do on February 14th 2007? Visualize your (digital) life in Org-mode
Python
998
star
2

filetags

Management of simple tags within file names
Python
199
star
3

LaTeX-KOMA-template

Generic template for midsize and larger documents based on KOMA script classes.
TeX
196
star
4

dot-emacs

My GNU/Emacs configuration
Emacs Lisp
177
star
5

org-mode-workshop

Workshop for Org-mode with focus on todo-, project- and workflow-management
161
star
6

github-orgmode-tests

This is a test project where you can explore how github interprets Org-mode files
146
star
7

date2name

Handling time-stamps and date-stamps in file names
Python
69
star
8

appendfilename

Intelligent appending text to file names, considering file extensions and file tags
Python
45
star
9

guess-filename.py

Derive a file name according to old file name cues and/or PDF file content
Python
39
star
10

extract_pdf_annotations_to_orgmode

Extracting RepliGo PDF annotations to a Org-mode format snippet (unmaintained!)
Shell
28
star
11

orgmode-ACM-template

Using new Emacs Org-mode LaTeX exporter to generate LaTeX/PDF files that meet the requirements of ACM (unmaintained!)
28
star
12

orgformat

Utility library for providing functions to generate and modify Org mode syntax elements like links, time-stamps, or date-stamps.
Python
27
star
13

tagstore

a research software; a fun way of storing files & folders on your local disk drive; tagging
Python
24
star
14

org-contacts2vcard

Converting Emacs Org-mode org-contacts contact information to VCard format suitable for importing to Android 4.4
Python
22
star
15

move2archive

Managing event-related files in a folder hierarchy like "<ARCHIVE>/2013/2013-05-17 Event name/"
Python
22
star
16

org-du

Visualizing Emacs Org-mode heading lines using du and xdu
Python
21
star
17

exchange2org

Connects to your Exchange server and extracts data in Org-mode format
Python
19
star
18

integratethis

Integrate programs or scripts into common tools like Windows Explorer context menu
Python
17
star
19

orgmode-iKNOW2012

Demonstrating the generation of an ACM paper using Emacs Org-mode and LaTeX export
Emacs Lisp
15
star
20

jira2org-story.py

Extract Jira Issues and Generate Org-mode Headings
Python
14
star
21

nixos-config

NixOS + flakes + home-manager with xfce, zsh, tmux, ...
Nix
13
star
22

twitter-json_to_orgmode

Converts the Twitter export files (JSON format) into an Emacs Org-mode file
Python
13
star
23

Student-Supervision-Process

How to organize supervision of the development of (LaTeX-) documents of students
12
star
24

title-capitalization.el

Proper English title capitalization of a marked region
Emacs Lisp
11
star
25

LaTeX-KOMA-VWA

Vorwissenschaftliche Arbeit (VWA) mit pdflatex/KOMA professionell gestalten
10
star
26

appendorgheading

Append a new Org mode heading to an existing Org mode file
Python
8
star
27

muttfilter.py

Per-contact FROM-email addresses for users of mutt and org-contacts.el
Python
7
star
28

convert_iCal_to_free-busy-only

Filter out things from an iCalendar file to publish free/busy information only
Python
7
star
29

filetagslib

Utility library for providing functions related to the filetags file name convention: https://github.com/novoid/filetags
Python
7
star
30

fetchphotos

A Python script to fetch data from a digital camera, rotating image files, renaming according to my file name convention.
Python
7
star
31

vkl

vkl - a better "ls"-experience
Python
6
star
32

recode-h107d-videos

Recode Hubsan x4 H107d video recordings in order to save space and correct the aspect ratio
Shell
6
star
33

orgmode-balance

Script that gives feedback on how you are doing in your Org-mode todos
Shell
6
star
34

getdigicamdata.sh

Fetching data from my digital camera, rotating image files, renaming according to my file name convention.
Shell
5
star
35

2011-01-tagstore-formal-experiment

Collected public data and tools concerning a formal experiment conducted with tagstore
Shell
4
star
36

postprocess_Org-mode_iCal_export

Adding reminder alarms (defined as Org-mode tags) to your iCalendar export file
Python
4
star
37

2011-04-tagstore-formal-experiment

Collected public data and tools concerning a formal experiment conducted with tagstore
Python
3
star
38

gettvthek

Downloads WMV files from ORF-TVthek
Shell
3
star
39

GenerateSeatingplan.py

Uses output-CSV files of CAMPUSonline containing students attending an exam and generates a randomized seating plan
Python
2
star
40

set_desktop_background_according_to_season

Sets the desktop backgrounds of OS X 10.5 according to photographs which are from a similar season
Python
2
star
41

LaTeX-CV-template

A bi-langual LaTeX template for CVs
TeX
2
star
42

org-mode-demodata

An Org mode file that contains data that should mimic normal day-to-day data
2
star
43

vkSenseCam

Download-script for Microsoft SenseCam or Vicon Revue v1
Python
1
star
44

orgdepend_to_orgedna

A Python script to convert Emacs Org mode files using org-depend to org-edna (dependency management)
Python
1
star
45

mediathekview_change_downloads_to_http

Modify pending MediathekView download URLs from https to http
Python
1
star
46

convert-OS-X-file-labels-to-filetags

This is a hack which searches and converts OS X 10.5 file labels to filetags
Shell
1
star
47

mailhours

Visualize the times of the day of emails sent by a certain person (maildir)
Shell
1
star