notroot (Posts about nikola)

Adding a Fediverse Share Button to my Emacs Nikola Blog

Notroot — Fri, 17 May 2024 19:46:34 GMT

I was browsing the Fediverse, as is my wont, and I came across a fella named Stefan Bohacek announcing the release of his new Fediverse Share Button. I tried it with my Sharkey instance and it worked! So I decided to add it to this blog. Even working with Nikola and Emacs, it was pretty frickin' easy.

To continue my very meta habit of writing about blogging on my blog, here's how I added the share button at the bottom of this page.

Install Fediverse Share Button

First, we simply need to clone the fediverse-share-button repo. I cloned it next to my blog directory to make it a little simpler to move files into place, like this:

cp -r ./fediverse-share-button/fediverse-share-button ./notroot-blog/files

That's it for now! Next, I'll show you how to incorporate those files into your Nikola builds.

I referred to this "Random Geekery" blog post to figure out how to tweak Nikola themes and templates to include my fancy new share button.

Boiling down my "learnings" (barf) for the reader, here's what I did.

Create a New Theme to Tweak

Rather than tweaking the installed theme – in my case, the hack theme – we want to inherit from it, and make the changes to our own theme templates.

First, I created a new theme called notroot, based on hack, like this:

nikola theme --new notroot --parent hack

Then, I changed my theme and disabled bundling in Nikola's conf.py, like this:

THEME = "notroot"
USE_BUNDLES = False

Then, I copied the post template into my new notroot theme, like this:

nikola theme --copy-template post.tmpl

To make sure my new notroot theme was exactly the same as hack, I did a quick built and served it locally, like this:

nikola build
nikola serve

Perfect! Nothing changed… yet.

Add Fediverse Share Button

Next, I opened the aforementioned post.tmpl file in Emacs, and more or less followed Stefan's instructions. However, because we're working with a Nikola template (Mako), there was a little more to it.

My post.tmpl has a block called extra_head, so that's where I added the CSS link. It should look sorta like this afterwards:

<%block name="extra_head">
<!-- ... the rest of 'extra_head' ... -->
<link rel="stylesheet" href="/fediverse-share-button/styles.min.css">
</%block>

Note that, unlike Stefan's instructions, we use an absolute path here /, not a relative path ./, to the fediverse-share-button/ directory. That's because Nikola will move things around when it builds, and because we just plopped fediverse-share-button into the files/ directory, it will be at the top level, next to assets/ and images/.

To include the <script> tag pointing to the Javascript for our share button, I had to add an extra_js block to the bottom of post.tmpl. It also uses absolute paths, like this:

<%block name="extra_js">
<script src="/fediverse-share-button/script.min.js" defer class="fsb-script"></script>
</%block>

Then, finally, I was able to include the actual button <form> element. I chose the bottom of the post, above the navigation. The whole content block, after my changes, looks like this (comments added for emphasis):

<%block name="content">
<article class="post-${post.meta('type')} h-entry hentry postpage" itemscope="itemscope" itemtype="http://schema.org/Article">
    ${pheader.html_post_header()}
    <div class="e-content entry-content" itemprop="articleBody text">
    ${post.text()}
    </div>
    <aside class="postpromonav">

	<!-- START fediverse-share-button form -->

	<form class="fsb-prompt">
	    <label>Share with the fediverse</label>
	    <div class="fsb-input-group mb-3">
		<span class="fsb-input-group-text">https://</span>
		<input required
		       type="text"
		       name="fediverse-domain"
		       placeholder="mastodon.social"
		       class="fsb-input fsb-domain"
		       aria-label="Amount (to the nearest dollar)">
		<button class="fsb-button"
			type="submit"><img src="/fediverse-share-button/icons/mastodon.svg"
					   class="fsb-icon"></span>Share</button>
	    </div>
	    <p class="fsb-support-note fsb-d-none">
		This server does not support sharing. Please visit <a class="fsb-support-note-link"
								      target="_blank"
								      href=""></a>.
	    </p>
	</form>

	<!-- END form -->

    <nav>
    ${helper.html_tags(post)}
    ${helper.html_pager(post)}
    </nav>
    </aside>
    % if not post.meta('nocomments') and site_has_comments:
	<section id="comment-section" class="comments hidden-print">
	<h2>${messages("Comments")}</h2>
	${comments.comment_form(post.permalink(absolute=True), post.title(), post._base_path)}
	</section>
    % endif
    ${math.math_scripts_ifpost(post)}
</article>
${comments.comment_link_script()}
</%block>

Then, once again, I built it and served it locally to check my work.

Style the Fediverse Share Button

Success! Except…

Except the CSS was all screwy. The share button itself was enormous, due to how hack CSS treats all <img> tags, and it was all left-justified, when my tags right below are centered.

Let's fix that!

It turned out to be dead simple. I inspected the classes in the browser, fixed it so it looked right, then copied those styles out of files/fediverse-share-button/styles.css and into my own files/assets/css/custom.css file. Then I added the attributes needed to fix things.

To fix the enormous button, I just added !important to max-width:

.fsb-icon {
  max-width: 1rem !important;
  margin-right: 0.5rem;
  vertical-align: baseline;
}

To get the whole shebang centered, I modified .fsb-prompt to add auto margins on the right and left, which effectively centered the <form> itself. I also had the form center text. It looks like this, now:

.fsb-prompt{
  max-width: 500px;
  margin-top: 52px;
  margin-left: auto;
  margin-right: auto;
  text-align: center;
}

And voila! Beautiful!

Build and Deploy

Once I was satisfied with the look and functionality, I was ready for the final build and deployment.

First, though, I needed to minify the CSS changes that I had made. Stefan describes this, as well – for both JS and CSS – but here's exactly what I did:

npm install minify -g
minify files/fediverse-share-button/styles.css > files/fediverse-share-button/styles.min.css

Finally I was ready to build and deploy, as usual, from within Emacs.

M-x nikola-build to build.
M-! nikola deploy to deploy.

Next Steps

Next steps are three-fold:

Publish this blog post to my blog.
Once published, I will click the Fediverse Share Button and share to my Fediverse account.
Then I will get the article ID of that Fediverse note, and add it to the meta for this post. Then I'll rebuild and redeploy. This will enable the "Comments" section, and replies to my Fediverse note will appear as comments on this blog post!

It's like frickin' magic, baby!

How I Made This Site (This Time)

Notroot — Sun, 07 Apr 2024 22:29:06 GMT

Someone on the Fediverse was curious how I made this site, since I mentioned using Emacs org-mode, and their own site is built using org-roam and Hugo.

It's not that much different from the more complicated process I was using before, on GitHub Pages. This one is simpler in one respect: I'm deploying directly to my own host, so I don't have to use the more complicated nikola deploy_github configuration, which requires separate source and deployment Git branches.

For reference, here's my original post on how to get Nikola and nikola.el working with GitHub Pages:

Publishing with Nikola in Emacs

This time, I'm going to take the reader through the setup, step-by-step.

Requirements

Here are the things you'll need for this tutorial. I'll show you some steps.

Emacs: Obviously. With Org Mode.
Git: Git and a private Git repository.
Nikola: Nikola is a static site generator, with an orgmode plugin.
nikola.el: nikola.el is an Emacs package that wraps Nikola functions.
Webserver: This setup assumes you have your own private webserver for deployment, but Nikola has a test server.

Install and Configure Nikola

From Nikola's installation instructions, slightly tweaked to use v8.2.4:

python3 -m venv nikola-env
cd nikola-env
bin/python -m pip install -U pip setuptools wheel
bin/python -m pip install 'Nikola[extras]==8.2.4'

You can now use Nikola by launching the script directly:

bin/nikola

Or you can activate the environment before working with Nikola and use the nikola command:

source bin/activate
nikola

Install Nikola add-ons

Now you need the Nikola orgmode plugin.

nikola plugin -i orgmode

And you need to install a Nikola theme. I chose the hack theme, but you can pick another.

nikola theme -i hack

Init Local Blog

Nikola sites require a particular directory and file structure, and it has a command to create that for us. Let's use that method, rather than more complicated options.

See Nikola's instructions, here. Here's what I recommend:

nikola init --demo <directory_name>
cd <directory_name>
git init

This creates the Blog structure, and also initializes the directory as a Git repository. You should continue and connect it to your Git repository, and push an initial commit.

The --demo option will fill in some blanks in your configuration file, and is recommended the first time.

Configure Nikola

Nikola settings live in the conf.py file that was created when you initialized your blog.

You can view the demo conf.py online, here.

Most of the settings are self-explanatory, and many of them have defaults. However, we do need to change a few things for our theme and the orgmode plugin.

Configure orgmode

At the bottom of conf.py, add the following:

# Add orgmode to compilers dict
COMPILERS["orgmode"] = [".org"]

# Add org files to posts and pages
POSTS = POSTS + (("posts/*.org", "posts", "post.tmpl"),)
PAGES = PAGES + (("stories/*.org", "stories", "story.tmpl"),)

This will allow you to write posts and pages for your blog in org-mode, with everything that comes with that.

Configure theme

Each theme may have particular settings to configure, but here are the ones for the "hack" theme.

Uncomment GLOBAL_CONTEXT, and set:

THEME = "hack"
# ...snip...
GLOBAL_CONTEXT = {}
GLOBAL_CONTEXT['HACK_VARIANT'] = 'dark'

I also have these additional settings:

DATE_FANCINESS = 2

# For Hack theme
NAVIGATION_LINKS = {
    DEFAULT_LANG: (
	('/index.html', 'Home'),
	('/archive.html', 'Archives'),
	('/categories/index.html', 'Tags'),
	('/stories/about-me', 'About Me'),
	('/rss.xml', 'RSS'),
    ),
}

Configure deployment

You will probably want to configure this after you've successfully built and deployed manually by your usual methods, so that you get the command right, but here's what mine looks like:

DEPLOY_COMMANDS = {
    'default': [
	"rsync -rav --delete output/ root@notroot:/var/www/blog.notroot.online",
    ]
}

I have my host notroot configured in my .ssh/config.

Install and Configure `nikola.el`

It's a bit outdated, and I can't get M-x nikola-deploy to work, but otherwise we want this.

Simplest thing is to use use-package. Here's my config:

;; Nikola.el config
(use-package nikola
  :config
  (setq nikola-output-root-directory "~/Dev/mine/notroot-blog/")
  (setq nikola-verbose t)
  (setq nikola-webserver-auto t)
  (setq nikola-new-post-extension "org")
  (setq nikola-new-page-extension "org"))

Then from inside your init.el buffer, do M-x load-file RET RET to install and configure nikola.el.

Write a Blog Post in Emacs

Now we can write a blog post, like this one, in Emacs org-mode. Super easy!

Just do M-x nikola-new-post to create a new posts, or M-x nikola-new-page to create a new page, like my "About Us" page.

Emacs will give you an *.org file, but will also create a *.meta file. Most things will be preset, but you will probably want to add tags. Here's the meta file for this blog post:

.. title: How I Made This Site (This Time)
.. slug: how-i-made-this-site-(this-time)
.. date: 2024-04-07 18:29:06
.. tags: nikola,emacs,org-mode,blogging,tutorial

And here's a screenshot of me writing this post! Talk about "meta" heheh:

Preview and Build

You can also preview your work.

Do M-x nikola-webserver-start and navigate to the URL shown in the mini-buffer.

To see changes in the blog post, you will need to stop it with M-x nikola-webserver-stop, and restart it. Nikola does not rebuild on save.

Run M-x nikola-build. You can watch the progress in the *Nikola* buffer.

How Nikola Builds

One of the nice things about Nikola is that it builds using Emacs org-mode export to HTML directly, rather than translating to another markdown format, first. No pandoc is involved. No intermediary *.md files.

The benefit is obvious: the HTML will exported from your org files pretty much how you expect.

The one exception I've found is that inter-org file links like [[file:another-blog-post.org]] will be turned into <img> tags, not <a> tags, which is too bad. That's because the slugs Nikola uses don't match org-mode's own. I'm sure there's an elisp workaround, but I haven't played with it, yet.

Fortunately, this is org-mode! If you need to link from one blog post to another, just do something like:

#+begin_export html
<a href="/posts/publishing-with-nikola-in-emacs/">Publishing with Nikola in Emacs</a>
#+end_export

Deploy Your Blog

The nikola-deploy command is, unfortunately, not working for me. I have forked this old project, and at some point I'll try to fix it, but for now, I just use the shell command in Emacs.

Do M-! nikola deploy to upload your site to your webserver.

Then browse to your new blog. If everything is working, you should be live!

Conclusion

Once you get Nikola and nikola.el working, this is a very easy way to blog, if you're an Emacs person. It's intuitive and highly configurable.

For example, Nikola does it's own syntax highlighting, but I'll be adding something like highlight.js down the road. I can add comments sections, and I've barely touched the possible Nikola add-ons.

If you're an Emacs person, I think this is one of the more flexible, but robust, SSG integrations out there. I, too, love the idea of publishing natively using only Emacs, but one of the great features of Emacs is also its ability to compose cleanly with other commandline tools.

Blog Upgrade

Notroot — Sat, 06 Apr 2024 21:38:32 GMT

I'm an engineer, and I'm an Emacs nut, so yes: I tinker a lot.

My latest tinkering was to move my Nikola- and Emacs-based blog out of GitHub, when I abandoned that service entirely, and moved all my code to GitLab.

My reasons for moving are pretty straightforward: I think the "AI" hype is bullshit, and I won't have anything to do with it. I certainly don't want Micro$oft training their "AI" LLMs on my code. Fuck our robot overlords. They can meet me in the street and we can fight it out.

GitLab also has "AI" features, but nothing like GitHub. What's more, I can host my own GitLab and eschew their "AI" fuckstickery, entirely. Can't do that with GitHub, so it was an easy calculus to perform.

I did try to use GitLab Pages, which is really part of GitLab CI, which is to say, "Pipelines".

Overkill, yo. Too much configuration-over-convention for my taste. I don't like Python Django, either, for the same reason. If I'm doing web work, gimme Flask any day of the week.

Anyhow, while I was moving my blog, I thought I'd give it a new look. No more white background, and no more left-aligned container div.

Still not much here on this pathetic blog, but maybe now that I can write and easily deploy to my own host, I'll actually blog a little more.

I might even write about something besides Emacs!

Ya never know…

Publishing with Nikola in Emacs

Notroot — Thu, 12 Nov 2020 22:25:34 GMT

Publishing Emacs Org Mode files to GitHub Pages with Nikola is fairly straight-forward. But if you want, as I did, to write and publish from within Emacs using org-mode, then there's more setup involved. It's still not terribly difficult, however. I did this all today.

The final blog is going to be very vanilla, so I've included some additional resources to play with, as much for my own reference as for you, the reader's.

UPDATES!

<2022-01-29 Sat> <2024-04-07 Sun>

The really nice tutorial linked to above and below is 404. Since this tutorial picks up where that one left off, I've added a few other links. Some of these are old. Some don't talk about Org Mode. But the objective is this:

Before continuing this tutorial, get Nikola to publish Org files from the command-line to your GitHub Pages. Here's some resources that describe how to do that:

I will try to come back and write my own command-line tutorial later as a prequel to this post.

Get Nikola Working

Before we start, save yourself a headache and don't install Nikola in a Python virtual environment. Or if you're using pyenv, install it in the global environment. This works fine in the terminal, but we're going to be writing some extra elisp for the nikola.el package. I have no doubt there's a way to get this package working with virtual environments, but as of this writing, I haven't figured it out.

Next, follow the instructions in this excellent tutorial to get all the pieces working together, and to learn the command-line way of doing things as a fallback.

The end result will be your first blog post on your GitHub Page. Now that you know it works, let's move on to setting up Emacs so you never have to leave it to write and publish.

Install and Configure `nikola.el`

We're going to use the "simple wrapper" nikola.el package as a base. Follow these instructions to install and configure it.

We want to default to Org files, instead of HTML, so here's the use-package config I have in my init.el. Note that I've turned on nikola-verbose and nikola-webserver-auto as well as setting the default extension to "org":

;; Nikola.el config
(use-package nikola
  :config
  (setq nikola-output-root-directory "~/Dev/mine/blog.notroot.online/")
  (setq nikola-verbose t)
  (setq nikola-webserver-auto t)
  (setq nikola-new-post-extension "org")
  (setq nikola-new-page-extension "org"))

Add Wrapper for `github_deploy`

At this point, we could just start writing by using the nikola-new-post command. It will open an Org file and you can start typing, as I am right now.

The problem comes when we run nikola-deploy. That command basically runs nikola deploy in a shell, but that's not the command we want to run. We want to run nikola github_deploy, as we did on the command-line.

So you'll also need to add the following nikola-github-deploy function to your init.el, which I simply whittled down from the nikola-deploy:

;; Custom nikola-github-deploy function
(defun nikola-github-deploy ()
  "Deploys the site to GitHub using github_deploy subcommand."
  (interactive)
  (message "Deploying the site to GitHub pages...")
  (async-start
   `(lambda ()
      ,(async-inject-variables "\\(nikola-\\)")
      (setq output nil)
      (let ((default-directory nikola-output-root-directory))
	(run-hook-with-args 'nikola-deploy-before-hook "")
	(if (not (eq nikola-deploy-before-hook-script nil))
	    (setq output (shell-command-to-string
			  nikola-deploy-before-hook-script)))
	(setq output (shell-command-to-string (concat nikola-command " github_deploy")))
	(if (not (eq nikola-deploy-after-hook-script nil))
	    (setq output (shell-command-to-string
			  nikola-deploy-after-hook-script)))
	(run-hook-with-args 'nikola-deploy-before-hook ""))
      output)
   (lambda (result)
     (if (cl-search "This command needs to run inside an existing Nikola site."
		    result)
	 (if (eq nikola-verbose t)
	     (message "Something went wrong. You may want to set nikola-verbo\
se to t and retry it.")
	   (message "Something went wrong. You may want to check the *Nikola*\
buffer."))
       (message "Site deployed correctly."))
     (if (eq nikola-verbose t)
	 (save-window-excursion
	   (switch-to-buffer "*Nikola*")
	   (let ((inhibit-read-only t))
	     (insert result)))))))

Write and Publish from Emacs

Now you can evaluate the init.el buffer, or restart Emacs, and do nikola-new-post. Emacs will ask for the title, and create the post files, and open a buffer to write a new post.

You'll immediately notice that, unlike the command-line experience you had earlier, the meta is not included at the top of the new buffer that opens. If your new post is named publishing-with-nikola-in-emacs.org, then the meta will be in the same directory, and named publishing-with-nikola-in-emacs.meta. You will have to edit it separately.

.. title: Publishing with Nikola in Emacs
.. slug: publishing-with-nikola-in-emacs
.. date: 2020-11-12 17:25:34
.. tags: emacs,nikola,blogging

When you're done writing your amazing blog post, just save it.

Now try previewing your new post by running nikola-webserver-start. Notice that that this is a live preview, and if you make changes and save again, you will see them when you refresh your browser.

Next, run nikola-build to make sure everything is rebuilt and updated.

When you're happy with the final result, then just publish it with nikola-github-deploy.

Additional Resources

Syntax Highlighting: If you included source blocks in your Org file, you probably noticed that syntax highlighting isn't supported. I'm going to look at org2nikola package to add highlight.js support at some point.
Themes and Templates: Since I'm almost as new at this as you, the reader, are, I've got jack. I'm going to look into Nikola theme creation at some point in the future, and if suddenly this blog looks better, it's because I learned something. I'll probably blog about it!

notroot (Posts about nikola)

Adding a Fediverse Share Button to my Emacs Nikola Blog

Install Fediverse Share Button

Create a New Theme to Tweak

Add Fediverse Share Button

Style the Fediverse Share Button

Build and Deploy

Next Steps

How I Made This Site (This Time)

Requirements

Install and Configure Nikola

Install Nikola add-ons

Init Local Blog

Configure Nikola

Configure orgmode

Configure theme

Configure deployment

Install and Configure nikola.el

Write a Blog Post in Emacs

Preview and Build

How Nikola Builds

Deploy Your Blog

Conclusion

Blog Upgrade

Publishing with Nikola in Emacs

UPDATES!

Get Nikola Working

Install and Configure nikola.el

Add Wrapper for github_deploy

Write and Publish from Emacs

Additional Resources

Install and Configure `nikola.el`

Install and Configure `nikola.el`

Add Wrapper for `github_deploy`