Miroirs/jorge
1
0
Fork 0
mirror of https://github.com/facundoolano/jorge.git synced 2024-11-16 07:47:40 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

add notes about jorge meta

Browse source
This commit is contained in:
facundo 2024-09-18 18:18:07 -03:00
parent b56ca9fba7
commit c23c184f5a
1 changed files with 34 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
docs/src/blog/turn-your-blog-into-an-ebook.org
View file

@ -16,12 +16,12 @@ Since then I've been trying to figure out what ebook generation in [[https://jor
1. Adding epub knowledge felt like it would double the scope and turn jorge into a mostly ebook-related project, which wasn't in my plans.
2. I'd have to choose between a very opinionated and simplistic API or one flexible enough to accommodate different use cases, neither of which felt satisfactory.
After [[https://olano.dev/blog/from-rss-to-my-kindle/][working on Kindle support]] for my feed reader and learning that epub files are mostly zipped HTML files, it became apparent that the basic site generation tools I already had should be enough to do the job.
Below are some implementation notes from composing an ebook from a subset of my blog posts, using a secondary jorge project. This code could eventually be extracted out to a sample repository or turned into a built-in project layout.
On a similar note, I didn't want to extend my site generator with hooks or a plugin system to enable loosely coupled ebook commands, nor did I want to create a standalone program for that purpose.
------
After [[https://olano.dev/blog/from-rss-to-my-kindle/][working on Kindle support]] for my feed reader and learning that epub files are mostly zipped HTML files, it became apparent that the basic site generation tools I already had should be enough to do the job.
The key reason this feature seemed approachable at all was that my blog post files are site-agnostic. The base website structure is defined by a layout template, and the blog posts only provide the content. I could reuse them without changes by just switching to a new layout template adapted to the epub format.
The necessary work can then be outlined as follows:
@ -35,7 +35,37 @@ The necessary work can then be outlined as follows:
8. [[https://github.com/facundoolano/olano.dev/blob/36d55236be42f06dc3c56b37b88a032f4953b825/book/Makefile#L8-L9][Build]] the jorge project, [[https://github.com/facundoolano/olano.dev/blob/36d55236be42f06dc3c56b37b88a032f4953b825/book/Makefile#L36-L37][zip]] the target directory into an epub file, [[https://github.com/facundoolano/olano.dev/blob/36d55236be42f06dc3c56b37b88a032f4953b825/book/Makefile#L39-L40][convert]] the epub to a pdf as an alternative format.
9. [[https://github.com/facundoolano/olano.dev/blob/36d55236be42f06dc3c56b37b88a032f4953b825/Makefile#L17-L18][Copy the resulting files]] into the parent src/ directory to serve them on the website.
Let's look at some code snippets to illustrate the outline above. The epub manifest in the ~OEBPS/content.opf~ file lists each post as a chapter and each image as a media item:
------
Once I had a working version of the book generation Makefile, I realized that I could simplify the process by making some site metadata available to scripts---the lists of posts and tags and site configuration already exposed to templates. So I added a new command for that purpose.
By default, [[https://github.com/facundoolano/jorge/pull/49][~jorge meta~]] dumps the entire site metadata as a JSON to stdout, but I made it also accept [[https://shopify.github.io/liquid/][liquid]] filter expressions, by hooking it to the template rendering [[https://github.com/osteele/liquid/][library]]:
#+begin_src shell
$ jorge meta 'site.tags|keys'
["emacs","thoughts","golang","project"]
#+end_src
#+begin_src shell
$ jorge meta 'site.posts | where:"lang","en"|map:"title"' | jq -r '.[]' | head -5
Are We Living in a Simulation?
My Software Bookshelf
Software Possession for Personal Use
Deconstructing the Role-Playing Video Game
A Computing Magazine Anthology
#+end_src
#+begin_src shell
$ jorge meta 'site.posts | where:"lang","en" | map:"src_path"' | jq -r '.[]' | head -5
src/blog/are-we-living-in-a-simulation.org
src/blog/my-software-bookshelf.org
src/blog/software-possession-for-personal-use.org
src/blog/deconstructing-the-role-playing-videogame.org
src/blog/a-computing-magazine-anthology.org
#+end_src
With the meta subcommand, the jorge plugin system is just bash.
------
Let's look at some code snippets to illustrate the implementation of the outline above. The epub manifest in the ~OEBPS/content.opf~ file lists each post as a chapter and each image as a media item:
{% raw %}
#+begin_src html
@ -71,8 +101,6 @@ posts:
| jq -r '.[]' | xargs -I {} cp {} book/src/OEBPS/Text
#+end_src
This relies on the new [[https://github.com/facundoolano/jorge/pull/49][~jorge meta~]] command to filter posts by their metadata.
Things got a bit complicated to render images since the relative path to the assets directory isn't the same in the website and the ebook project:
#+begin_src Makefile
INLINE_IMAGES:=$(shell grep -oRSh 'static_root*[^"[:space:]]*' src/OEBPS/Text | sort | uniq | sed -E 's|static_root}}/img/||')