otherjoel / thenotepad

📓🍎An experimental blog written in Pollen / Racket

The Notepad

A blog created with Pollen. The live site is at https://thenotepad.org. See LICENSE for copyright/licensing information.

Background

Pollen is really optimized for books, where the sections are finite and can be prearranged according to the logic of the subject matter. It takes some extra work to put it to use as a blog, which by analogy is a loose sheaf of papers that need constant reshuffling before any use can be made of them.

Nonetheless, it works pretty well as a static blog generator. Pollen comes with no opinions about your site so there's no cruft to clean out or hack around. Pollen also gives me capabilities I can no longer live without — first among which is, it allows you to design your own markup and control how it works, forever. More thoroughly tedious rationale for my design choices will eventually go on the site’s About page.

Features

• An RSS Feed
• Generates PDF versions of every post
• Includes “Topics”, a tagging system
• Makefile for incremental builds
• Pollen tags for perma-embedding Tweets in web and PDF output (no JavaScript)
• Example dynamically generated index.ptree — no need to edit every time you add a new post
• Semantic line wrapping

Support

If you find this project helpful, please consider chipping a few bucks towards the author!

Setting up your own copy

• You'll need xelatex installed and in your PATH to generate PDFs. On Mac, installing MacTeX is easy and will do the job.
• You'll need to install Racket, and the Pollen package
• Ideally you'll be on a system that can run Bash scripts and the GNU make utility
• If you do use the included makefile to build the site, you will want to install HTML5 Tidy — or remove references to the tidy command in the makefile. (Note: Many operating systems come with a version of tidy pre-installed, but it is usually very out of date and will throw errors when used with this repo.)

Next, just plop all the files from this repository in a folder. Run make all from the command line in this folder to build all the static HTML files. Run make pdfs to build the PDF versions of each post. (This is done separately because it is so much slower than building the HTML.)

To start writing your own content, move the included posts directory out of the way. You may wish to keep it around under a different name in order to refer to it for examples:

mv posts posts.example; make zap;

The make zap cleans out the top-level pages and the SQLite cache used to build them.

Finally, edit feed.xml.pp, filling in your own RSS metadata.

Tinkering

Blog posts should be named your-post-name.poly.pm and placed in the posts/ subfolder. Make sure the first line is #lang pollen and use ◊define-meta to specify the title, publish date, and, optionally, “topics” (basically tags). Check out the existing .poly.pm files in that folder for more examples of how things are done.

If you really want to customize anything, you will need to learn all about Pollen!

As in any Pollen project, you can test-run the site locally by running raco pollen start from the project folder. Then browse to http://localhost:8080 in your browser.

From the project folder, run make all to generate all the static HTML files for the site. This is an incremental rebuild: if you’ve built the site once and since done nothing but add a new post, make all will build the HTML files for that post, rebuild the Index and Topics HTML pages, and rebuild the RSS feed. If you change any of the Racket code (.rkt files) or any of the template files, it will rebuild the HTML files for every single post, depending on what you changed.

Use make zap to clean out all the generated pages, which will force a complete rebuild next time you do make all.

In order to speed up rendering of index.html and other top-level pages, I have implemented an additional caching system in an SQLite database. See the post Using SQLite to Speed Up Pollen Renders to understand how it works.

Finally, you can use make publish to push all necessary static files to your web server. See makefile for more details; you'll need to configure a couple of environment variables and you also need to be able to ssh into your server passwordlessly.

Contributing

See Contributions for guidance on submitting issues and pull requests to this repo.

Forking

Please feel free to fork this repo! If you do so, be sure to edit CONTRIBUTIONS.md to reflect your preferred guidance for potential contributors. Also note you must abide by the license terms, so please review those carefully.

If you want your improvements and customizations to be more generally known, feel free to let me know; I’ll be happy to add a link to it in the section below. (Alternatively, add a link to it in this file yourself and submit a pull request.)

Existing forks

None yet!

thenotepad's Issues

Call to mvim

I'm not sure about Mac, but usually on a UNIX system, instead of hard-coding the editor you would call out to whatever $EDITOR contains. Failing that, a somewhat sane default can be employed, for example emitting a message that tells the user to set $EDITOR.

What's your take?

Make errors

Hi, I am starting to get my hands dirty with thenotepad.

Following the instructions, I get a compiled site, but I wondered whether I should be concerned about a bunch of errors and warnings I got during my first make, such as:

Config: unknown option: drop-empty-elements
Error: Can't open "no"

line 33 column 9 - Error: <header> is not recognized!
line 33 column 9 - Warning: discarding unexpected <header>
line 35 column 13 - Error: <nav> is not recognized!
line 35 column 13 - Warning: discarding unexpected <nav>
line 42 column 13 - Warning: discarding unexpected </nav>
line 43 column 9 - Warning: discarding unexpected </header>
line 45 column 9 - Error: <article> is not recognized!
line 45 column 9 - Warning: discarding unexpected <article>
line 46 column 13 - Error: <header> is not recognized!
line 46 column 13 - Warning: discarding unexpected <header>
line 46 column 225 - Error: <time> is not recognized!

All of the pages generated similar errors; you can see them here, if you want:
https://gateway.ipfs.io/ipns/QmZJBQBXX98AuTcoR1HBGdbe5Gph74ZBWSgNemBcqPNv1W/internetapocalypse/Installation+first-make.md (jump to: "###First make")

Extending poly-branch-tag to allow default values for positional args

Hi Joel,

thanks for describing the macro that allows to split pollen tag functions into more sensible (to me) logical units. I am currently using it and enjoy it quite a bit. However, I did notice one thing today, which is why I am writing to you. There currently is no way to specify a default value for positional arguments.

My current situation is as follows (I hope this illustrates the issue): I'd like to have a special tag function for linking to Wikipedia entries, named link-wiki. I've declared it as

(poly-branch-tag link-wiki url)

And usually write ◊link-wiki["url"]{URLs ...} in the source file. What often happens is that the link text and the URL are the same, i. e. ◊link-wiki["kerning"]{kerning}. What I'd love to have is an option of not specifying the URL, should the text also be the link target.

Unfortunately it does not work with default arguments either at the poly-branch-tag specification (as they'll turn into attributes) or at the definition of html-link-wiki (as those defaults will be overridden by the macro). I'd prefer to not turn it into a kwarg/attribute so that the notation stays simple and I don't have to specify #:url every time I need to set the URL explicitly.

I was wondering whether it's possible to specify default values not only for attributes, but also for the positional arguments. It seems that the notation for default arguments is a bit overloaded, so I am not sure if the current approach you have outlined can be easily adapted. I'd love to hear your thoughts on it, as I have to admit that my ability to write macros is essentially nil.

Thinking about it, maybe the notation for the macro could look like

(poly-branch-tag link-wiki url 'default (attr1 "default"))

if that can be implemented? Not entirely sure whether macros have information about whether the arg is an unbound variable or something else; my first guess would be no.

In any case, sorry for ambushing you with this and thanks again. If you don't feel like diving into this, please let me know, that is of course perfectly alright, too.

--
Cheers,
Nik

PS: I was thinking about RSS feeds recently and then got your newsletter about splitflap a couple of days later, which made me happy and I hope I get take a look at it soon. Unfortunately I cannot watch the stream live as the timezone shift is too much but thank you for doing that!

PPS: I originally wanted to write you a mail to the mail address [email protected] but the mail bounced, so there might be something wrong with the mail setup for this domain.

Pages revamp

Let me know if you disagree, but I think the pages mechanism need a revamp.

Right now, pages live in the top-level directory and are hardcoded in the link bar and the makefile. I think they need to go in their own dir and then get collected automagically.

I might do this myself at some point.

Messed up PDF files

Hi Joel,

I'm not sure if you've noticed or not, but the content of the PDF files on https://thenotepad.org are messed up, they don't correspond to the post they're linked in (or to their name).

PDF links broken in pages that aren’t “posts”

For example, about.html and books.html

error: not rendering at books.html

hi

I was looking for something like this. ty for sharing
making the projects errors at book.html.pm

any help?

raco pollen render books.html
pollen: rendering books.html
standard-module-name-resolver: collection not found
  for module path: Pollen/lang/reader
  collection: "Pollen/lang"
  in collection directories:
   /home/user0/.local/share/racket/8.3/collects
   /usr/share/racket/collects/
   ... [173 additional linked and package directories]
  context...:
   /usr/share/racket/collects/compiler/private/cm-minimal.rkt:740:23
   /usr/share/racket/collects/syntax/private/modcode-noctc.rkt:36:2: reader
   /usr/share/racket/collects/syntax/private/modcode-noctc.rkt:259:5: compile-one
   /usr/share/racket/collects/compiler/private/cm-minimal.rkt:685:0: compile-zo*
   /usr/share/racket/collects/compiler/private/cm-minimal.rkt:451:15
   /usr/share/racket/collects/compiler/private/cm-minimal.rkt:440:12: build
   /usr/share/racket/collects/compiler/private/cm-minimal.rkt:411:0: maybe-compile-zo
   /usr/share/racket/collects/compiler/private/cm-minimal.rkt:209:0: compile-root
   /usr/share/racket/collects/compiler/private/cm-minimal.rkt:105:4
   /home/user0/.local/share/racket/8.3/pkgs/pollen/pollen/private/cache-utils.rkt:67:0: path->hash
   /home/user0/.local/share/racket/8.3/pkgs/pollen/pollen/private/cache-utils.rkt:124:2: generate-dest-file
   /usr/share/racket/collects/file/cache.rkt:63:2: fetch-and-continue
   /usr/share/racket/collects/racket/contract/private/arrow-val-first.rkt:555:3
   /home/user0/.local/share/racket/8.3/pkgs/pollen/pollen/private/cache-utils.rkt:114:0: cache-ref!
   /usr/share/racket/collects/racket/private/more-scheme.rkt:377:2: hash-ref!
   /home/user0/.local/share/racket/8.3/pkgs/pollen/pollen/cache.rkt:39:4: cached-require-base
   ...
make: *** [makefile:85: books.html] Error 1

Xelatex errors in articles referring to “print versions” of figure images

Pointed out to me in an email correspondence: people who are not me will get errors from xelatex when rendering some posts to PDF.

In publishing-dicewordbook.poly.pm I use this tag:

◊figure["dwb-qr1.jpg" #:has-print-version #t]{Page of QR codes from the first version of the book}

The idea with the has-print-version attribute of figure is that a high-res image (stored in posts/img/original/ will be used for PDF output, and a more size-optimized version (stored in posts/img will be used for web output.

The problem is that for both licensing and practical reasons, I don’t include the high-res images in this repo, so other people who clone it won’t be able to build those articles.

As long as people have the dependencies mentioned in README, they really should be able to do make all and make pdfs without errors.

LaTeX garbles UTF-8 characters when inside blockcode

This is a known problem with the lstlistings environment. Probably need to switch to using minted or some other package.

features from try-pollen in thenotepad?

Hi, this isn't really an issue, but a question.

First off, I have spent many weeks reading about Racket, Pollen, Frog, and several other good projects –and then I came across your work! Wow! I commend you! Taking all this time to evaluate the respective pros and cons will pay off. The Notepad is practically everything I have in mind.

• It's book-like but can handle an index of new bloggy posts
• It's beautiful (I share your and Mathew Butterick's love for tasteful typography and ergonomic UI)
• The ergonomic sidenotes and footnotes and your improvement of their contents are wonderful
• The ability to collect many-to-many relationships
• The make part of the generation should grant ways to manage a site hosted on ipfs.io and its content-addressed links. This distributed hosting capability will be the focus of my first site.

I've already installed the dependencies for both thenotepad and try-pollen and I decided to go with thenotepad and try to add to it things from try-pollen and beautiful-racket that might have not made it into thenotepad. I do like the left column chapter indexes seen in Beautiful Racket and I like the top previous and next links in one of your e-books.

So for example, on my second site (the raison d'être of the first), I want that ability to group by series that's in try-pollen. I wondered whether topics tagging in thenotepad is an evolved abstraction of that.

I have similar use-cases for separate groupings, such as glossary (similar to the docs links in Beautiful Racket), "people" (researchers who have metadata but are not necessarily authors) -for example in radio interviews involving several people in a roundtable, etc.

Your work with Matthew on multi-target will permit me to export subtitle files, one of the important goals of my site.

I wondered about the nifty fonts (E. Tufte) and its CSS used in The Local Yarn and your other gorgeous e-books. Are the CSS's going to be incompatible with each other or the HTML generation templates?

Well, that's a lot to ask. But I promise I will eventually be able to contribute to documentation, especially from a novice's perspective. I already have notes piling up on some Latex gotchas with OSX.

Do you prefer this kind of question on the Google group?

LaTeX special characters inside blockcode breaks PDF generation

Warning: <a> escaping malformed URI reference

I wasn't able to tell exactly what is going on here but I thought you might want to know about it:

rendering: /posts/writemonkey-tips-and-tricks-for-writers.poly.pm 
as /posts/writemonkey-tips-and-tricks-for-writers.html
"CREATE TABLE IF NOT EXISTS `posts` 
(`pagenode`, `published`, `updated`, `title`, `header_html`, `html`, PRIMARY KEY (`pagenode`));"
"CREATE TABLE IF NOT EXISTS `posts-topics` 
(`pagenode`, `topic`, PRIMARY KEY (`pagenode`, `topic`));"
"INSERT OR REPLACE INTO `posts` 
(`rowid`, `pagenode`, `published`, `updated`, `title`, `header_html`, `html`) values 
((SELECT `rowid` FROM `posts` WHERE `pagenode`= ?1), ?1, ?2, ?3, ?4, ?5, ?6)"
"DELETE FROM `posts-topics` WHERE `pagenode`=?1"
"INSERT INTO `posts-topics` (`pagenode`, `topic`) VALUES 
(\"posts/writemonkey-tips-and-tricks-for-writers.html\", \"Markdown\"), 
(\"posts/writemonkey-tips-and-tricks-for-writers.html\", \"WriteMonkey\"), 
(\"posts/writemonkey-tips-and-tricks-for-writers.html\", \"text editing\")"
cpu time: 557 real time: 560 gc time: 54
line 46 column 432 - Warning: <a> escaping malformed URI reference
line 46 column 432 - Warning: <a> illegal characters found in URI
line 46 column 470 - Warning: <a> escaping malformed URI reference
line 46 column 470 - Warning: <a> illegal characters found in URI
line 46 column 537 - Warning: <a> escaping malformed URI reference
line 46 column 537 - Warning: <a> illegal characters found in URI
line 46 column 450 - Warning: <a> escaping malformed URI reference
line 46 column 450 - Warning: <a> illegal characters found in URI
line 46 column 432 - Warning: <a> escaping malformed URI reference
line 46 column 432 - Warning: <a> illegal characters found in URI
line 46 column 511 - Warning: <a> escaping malformed URI reference
line 46 column 511 - Warning: <a> illegal characters found in URI
line 46 column 586 - Warning: <a> escaping malformed URI reference
line 46 column 586 - Warning: <a> illegal characters found in URI
line 46 column 467 - Warning: <a> escaping malformed URI reference
line 46 column 467 - Warning: <a> illegal characters found in URI
line 46 column 430 - Warning: <a> escaping malformed URI reference
line 46 column 430 - Warning: <a> illegal characters found in URI
line 46 column 482 - Warning: <a> escaping malformed URI reference
line 46 column 482 - Warning: <a> illegal characters found in URI
line 46 column 445 - Warning: <a> escaping malformed URI reference
line 46 column 445 - Warning: <a> illegal characters found in URI
line 46 column 455 - Warning: <a> escaping malformed URI reference
line 46 column 455 - Warning: <a> illegal characters found in URI
line 46 column 483 - Warning: <a> escaping malformed URI reference
line 46 column 483 - Warning: <a> illegal characters found in URI
line 46 column 468 - Warning: <a> escaping malformed URI reference
line 46 column 468 - Warning: <a> illegal characters found in URI
line 46 column 497 - Warning: <a> escaping malformed URI reference
line 46 column 497 - Warning: <a> illegal characters found in URI
line 46 column 383 - Warning: <a> escaping malformed URI reference
line 46 column 383 - Warning: <a> illegal characters found in URI
line 46 column 414 - Warning: <a> escaping malformed URI reference
line 46 column 414 - Warning: <a> illegal characters found in URI
line 46 column 506 - Warning: <a> escaping malformed URI reference
line 46 column 506 - Warning: <a> illegal characters found in URI
line 46 column 575 - Warning: <a> escaping malformed URI reference
line 46 column 575 - Warning: <a> illegal characters found in URI
line 46 column 455 - Warning: <a> escaping malformed URI reference
line 46 column 455 - Warning: <a> illegal characters found in URI
line 46 column 568 - Warning: <a> escaping malformed URI reference
line 46 column 568 - Warning: <a> illegal characters found in URI