Back to the talks
Previous by track: Questions and answers to help you fly with Hyperbole
Next by track: Bookclub tapas
Track: General
Gardening in Emacs: A Windows user's tale of tending, tweaking, and triumph
Marco Bresciani - Pronunciation: mˈarko breʃˈanɪ, Delta Chat, @AAMfP@fosstodon.org, marcoxbresciani.codeberg.page
Format: 18-min talk ; Q&A: ask questions via Etherpad/IRC; we'll e-mail the speaker and post answers on this wiki page after the conference Etherpad: https://pad.emacsconf.org/2025-gardening
Etherpad: https://pad.emacsconf.org/2025-gardening
Status: TO_REVIEW_QA
Duration: 17:36 minutes00:05.980 Introduction 00:39.040 What is a digital garden? 02:11.520 Why a digital garden? 03:39.200 How to digital garden? 04:57.440 How to make Emacs portable, on Windows 08:18.820 My Emacs customization 10:36.120 PlantUML and Japanese 14:50.660 My Org Mode publishing configuration 16:04.520 The final result 17:03.280 Thank you for listening
Description
I'm a not-ashamed Windows user, both at work and at home, since forever. I also like portable applications, to bring everything I need, everywhere, on my tiny USB thumb drive. And now also Emacs is there, on my USB!
I'm also not the blogger type of person: I've tried, for a time. I stopped at entry ~8 of a "100 days blogging" saga.
But I actually immediately fell in love with the (possibly slower pace) digital garden concept and since I wanted to try Emacs, I decided to catch two pigeons with one stone.
This is the story of how I learned the very basics of Emacs and Org Mode, from how to save and exit to how to change letters case of a whole region or the (long searched for) fill-paragraph feature.
This is the story of how I learned Org Mode publishing configuration and
tricks, to create my digital garden, give it a structure and make it
freely available for anyone to read (and hopefully enjoy) in HTML format.
This is the story of how I added Japanese furigana and PlantUML diagrams
and a one few clicks-away "go to market" strategy.
This is the story of my digital garden, how I tend to it while learning the tool(s) I'm using to care of my garden, Emacs and Org Mode. And this is the story of how I ask for your help, to continue learning Emacs and Org Mode.
About the speaker:
20+ years software developer and Vi user during university life, now moved to the dark side of agile coaching as Scrum Master. Started learning Emacs by chance since I wanted to try it since ages.
Transcript
[00:00:05.980] Introduction
Hello, everyone. My name is Marco
and today I'll talk about gardening with Emacs.
Gardening? Yes, but digital gardening, obviously.
But first, one thing: I'm sorry, yes,
I'm a Microsoft Windows user.
I know, I know. I said I'm sorry.
Please stick with me.
Do not skip this talk!
Promise, I'll show you only free software!
And speaking about free software,
yes, this presentation is not made with Emacs,
but I made it with LibreOffice.
[00:00:39.040] What is a digital garden?
So what is a digital garden?
A digital garden is
your personal corner of the internet
to cultivate ideas.
Think of it like a real garden
where you plant seeds (your new thoughts),
you water them (you add the details),
and watch them grow.
Unlike a fixed-date blog,
which shows only polished results,
a garden includes works-in-progress--
like seedlings in a greenhouse.
It's a network of notes
connected by links and tags,
helping you see patterns in your thinking.
Here, the ideas are not static;
they evolve as you learn,
creating a living archive of your mind,
just like the plants in a garden grow.
Also here, instead of the blog platform,
you decide the tools, the look, and your pace.
I'll show you how I run my garden
with plain Org Mode files
and our favorite Emacs.
In short: a digital garden
is a flexible, pressure-free space
to explore, learn in public
and connect the knowledge--
your own digital ecosystem.
[00:02:11.520] Why a digital garden?
Why a digital garden?
Well, a digital garden keeps knowledge alive:
instead of freezing content after "publish,"
you revisit and refine it,
so ideas stay accurate and useful.
By sharing half-formed thoughts early,
you lower the barrier to writing
and let concepts evolve gradually--
no need to wait for one "perfect" essay.
Links and tags weave ideas together,
revealing unexpected patterns
that isolated posts would hide.
This approach sheds perfectionism,
encouraging small, regular updates
that build momentum and invite collaboration.
Well, actually, even not regular updates are fine.
Early readers can offer feedback, share resources,
or identify blind spots,
accelerating your and their improvement.
Over time, your garden can become
a searchable showcase of your thinking,
a living résumé for collaborators, peers,
or anyone curious about how you learn.
And what about me?
Why a digital garden?
Well, I actually have started a digital garden
to learn Emacs and Org Mode.
[00:03:39.200] How to digital garden?
How to digital garden?
Well, start simple.
Pick one place for your notes
and put them online.
Even the worst Github ever out there is fine.
Then, well, maybe you can move out of GitHub,
but that's another story.
Capture your ideas quickly.
Publish them, even rough,
and maybe, if you want, tag them as seeds
to let the other people know they are rough.
Learning in public is useful
because link-related pages
so that readers can work through your thinking,
helping them see your connections.
Once a week or whenever you want,
prune outdated pieces if you want
or keep them there
and add fresh insights if you have any.
Share your updates openly.
Invite comments because steady small steps
will keep the garden thriving.
And what about me?
How I do digital garden work with Emacs?
With Org Mode and its publishing to HTML file,
and we will see it in a moment.
[00:04:57.440] How to make Emacs portable, on Windows
How to make Emacs portable on Windows
is the first topic.
Well, being in Windows,
I have the advantage and the possibility
to bring and use my data
and software basically everywhere:
home, office, my sister-in-law's PC
when she needs technical help,
friends and the like.
So for these reasons,
it's been many, many years
I'm using exclusively portable applications
that do not need an installation
and bring their own data
and configuration bundled together.
And now also Emacs is portable,
inside my tiny, really tiny, USB key.
How?
I mean: not being sure
if my USB key drive letter
will be D:, E:, K:,
or whatever other drive letter
will be assigned to it
by the system I'm plugging it into,
how can I specify, to Emacs,
that its home folder is on my USB?
Well, I could maybe have used relative paths,
but then, where's the fun of hacking things?
The trick here is
the not-so-well-known ~dp0 system variable
that contains the execution directory
full path of the executable file.
And yes, it ends with a backslash,
so composing it with other literal paths is ugly as well.
The ~dp0 variable is only available
inside a batch file during its execution,
and expands to the drive (d) and the path (p),
in which that batch file (0th)
command line parameter is located
(that obviously cannot change
because it's executing).
The data are obtained
from the %0 system variable
that contains the batch file name.
I actually have never tried,
but it should even allow to let the batch run
from a UNC network location
with no mapped drive letter at all!
And that's the batch file
I'm using to run Emacs with an automatically selected
and fixed Emacs folder,
emacshome folder,
sibling of the unzipped Emacs one,
regardless the computer I'm in
and the assigned drive letter.
If you need a portable Emacs,
this is probably the simplest way to go!
Just put the runemacs.bat file
in your unzipped Emacs
(well, 30.2 actually now) bin folder,
and your Emacs and its configuration
will always be there with you.
With this, I'm basically
creating the possibility
to bring my own digital garden with me,
just like a little desk Zen garden,
and together with it, also,
all the tools that I need to work on it,
always with me, in my USB key.
[00:08:18.820] My Emacs customization
Speaking about configuration,
here comes the second topic:
my Emacs customization.
Having a portable Emacs allows to
always have the configuration with me.
Yes, okay, but which configuration?
Well, obviously, I'm speaking of the init.el file
that lives inside of the emacs.d folder
in my emacshome portable configuration folder
that we just saw.
I'm not an Emacs expert,
but I want to highlight a point here
that has to be clear to every one of us:
the set of basic considerations I had
for text width, tabs versus spaces,
trailing spaces, and so on.
As you can see here,
I'm pretty opinionated,
but this is the important part:
we are lucky enough to be able to use Emacs,
that is presumably
the most highly configurable tool ever,
so let's use it!
Remember that it's your Emacs,
and you can and must configure it
for your needs,
even if it might seem ridiculous to others.
Here, the configuration you see
is not the important part.
The important part is how you feel
with your configuration.
For example: I have a fill-column-indicator
at 72 characters,
I prefer spaces instead of tabs,
no trailing spaces, truncate lines, and so on.
It might seem weird to some of you
and to most of my colleagues
(and friends as well,
but that's another story!)
and it might even be.
But I'm comfortable with my configuration,
and you should be with yours too.
That is: as an owner and worker
of my own digital garden,
it's obviously easier for me
to choose my own tools
and adapt those to my needs,
instead of the opposite!
If I want to put the roses
in a circle instead of a row
that is maybe the best practice, who cares?
It's my garden, and I use it as I want.
[00:10:36.120] PlantUML and Japanese
Continuing on the configuration party,
the third topic is PlantUML and Japanese.
Why those two are listed together?
Well, they are weird enough
to be both part of my configuration.
First, I think PlantUML
is a very nice and powerful tool,
so integrating it in Emacs
is pretty useful,
even if I'm currently using it
only to generate SVG images
when publishing my digital garden to HTML.
There are some pain points
that I still have to solve,
and I know that it's also possible to use it
for (pre)viewing diagrams
directly in Emacs, without publishing,
but maybe I don't need this feature at the moment.
And I have to thank our favorite Sacha Chua here,
because she taught me (through Mastodon)
how to automatically answer y,
when publishing in HTML,
every time that PlantUML has to (re)generate an SVG.
So, thank you Sacha.
Moving to Japanese, let me go back to
the previous slide for a moment
to show you a bit more in detail
the coding system I've configured.
If this PC is helping me in moving
back to the previous slide.
Okay, so let me... No, it's not working.
It's not... Okay.
So, speaking about Japanese,
I have studied Japanese.
My wife is Japanese,
but that's a detail.
So I frequently write in Japanese,
and I wanted to write in Japanese
also inside Emacs.
I learned, as you can see,
that UTF-8 DOS
is a more than enough coding system
to allow me writing in the same file,
both Italian with all our accented letters
and Japanese through Windows IME system.
This allows me to properly write, save, read files,
but it was not enough for copying
and pasting Japanese text.
If I copied some Japanese text from the browser
or even from another text editor,
it didn't work.
It only pasted the rubbish in Emacs
until I found out that for whatever reason,
I had to use, as you can see in bold,
UTF-16LE DOS for the selection coding system.
And this basically allows me
to copy Japanese from another file,
text editor, browser, whatever,
and paste it in Emacs and vice versa.
So the lesson here is,
if you need European languages
and Japanese inside your Emacs,
well, this coding system works.
Let me go back to PlantUML and Japanese.
Another interesting thing about Japanese
is this nice macro I found
in the Emacs mailing list
to add furigana to Japanese kanjis
when exporting or publishing to HTML.
It's actually even possible to do the same
with LaTeX export/publish
and I'll give you some references later.
It's very useful because I can show,
as you can see on the example at the bottom,
I can show the easier-to-read pronunciation
even for readers with really basic knowledge of Japanese.
(And it's also useful to myself, actually,
to remember how to pronounce those kanji!)
For those of you that have no idea
on how to read or write Japanese, well, sorry.
As you can see, the garden evolved from the beginning
on how to use Emacs and Org Mode,
and it's evolving further,
and here it's becoming open to
different plants (or PlantUML…)
and also be able to adapt
to different foreign visitors' needs.
[00:14:50.660] My Org Mode publishing configuration
Third topic: my Org Mode publishing configuration,
or where the digital garden is born.
The latest (but not least!) part of
the creation and tending of my digital garden
is the publishing file that is needed to export
the whole Org Mode project into HTML.
Here I do not have many fancy configurations,
even though I'm copying the publishing.el file itself
in the output folder,
to make it available in the published version of the garden.
Also I have added the mentioned configuration
to manage SVG (or PNG) exports from PlantUML
(thank you again, Sacha),
and I'm also forcing HTML5
without scripts as the result format.
Together with this,
I also have a fancy CSS addition
to the default one
that uses the System Font Stack concept
to harmonize fonts
with readers' local systems,
without downloading or injecting
external fonts.
I've customized links and tags a bit,
with the CSS, together with tables
and some other pieces here and there,
but nothing too much fancy.
[00:16:04.520] The final result
So, this is one (not-so-)random page
of my digital garden,
or my knowledge 枯山水,
my knowledge Zen garden, as I prefer to call it.
This is, specifically, the page related
to write about the Digital Garden concept itself,
as a sort of meta-writing.
You can see the different
rendering of the links,
depending if they are internal, in blue,
or external to the garden in gray-ish.
You can see the Japanese furigana
on top of the kanjis,
and you also can see the automatic table of contents,
the custom aside component that highlights
the latest modification date, and so on.
Everything I've spoke about here
is available in my digital garden
in my knowledge kare-san-sui, again,
as a sort of self-description
of the digital garden itself.
[00:17:03.280] Thank you for listening
Thank you, everyone,
for being with me till the end.
So as I said, if you want more details
about these topics,
take a look at my knowledge kare-san-sui.
The link is here, and feel free to contact me
through Delta Chat
at this email address.
Yes, I know.
It's a Microsoft email address.
It's an old one.
I recycled it. I know. It's my fault.
Thank you again, and happy Emacs everyone!
Captioner: rodion
Questions or comments? Please e-mail emacsconf-org-private@gnu.org
Back to the talks
Previous by track: Questions and answers to help you fly with Hyperbole
Next by track: Bookclub tapas
Track: General