Jake LaCaze


Using GitHub to host Markdown files

Why should developers be the only ones who get to have fun with GitHub repositories? Writers can get in on the action too.

The point of this post is not to teach you how to use git and GitHub. You can find other resources to help with that. I intend only to explain why GitHub might be a good option for hosting Markdown files for cross-platform writing.

The problem

My digital writing workflow was straight forward as long as I was using only devices made by Apple (Mac mini, iPad, and iPhone) and could sync all of my Markdown files via iCloud. However, I ran into a problem whenever I re-purposed an old Asus laptop by installing Fedora 35, converting the laptop into a Linux desktop. (I call it a “Linux desktop” because the display no longer works, but the laptop projects onto an external display via the HDMI port).

I knew of no way for a Linux computer to sync with iCloud, so I had to look for a third-party syncing solution.

Failed options

Following is a snapshot of some other options I tried before settling onto GitHub.

Dropbox

Technically, Dropbox could have worked–if I were willing to pay $9.99 a month (or $11.99 a month if I didn’t pay for a year upfront) for the Plus plan. But I didn’t want to pay just for syncing Markdown files. It’s not as if I have a huge library taking up gigabytes of storage, so anything more than $2 a month feels like a waste of money.

I could have stuck with the free plan if I were willing to limit myself to only 3 devices. But I instead chose to stick with my 4:

I also considered Dropbox Paper. While Paper does respond to some Markdown, I ran into a couple issues:

I appreciate that Markdown allows flexibility for editors–I don’t want to be locked into a certain app or ecosystem. I write my Markdown files in iA writer on Mac and iOS. iA writer does not have a Linux client, so on Linux I use Typora.

Box & Google Drive

Box looked like a great option, especially since I have 50GB free due to some promotion from a few years ago.

But Box doesn’t have a Linux client. And using WebDAV has never seemed reliable to me.

Also, Google Drive no longer has a Linux client. Boo!

Obsidian

I considered going the second brain route with Obsidian, but Apple devices sync Obsidian vaults only via iCloud, unless I want to pay $8 a month for Obsidian Sync.

No, thank you.

Nextcloud

I considered using Nextcloud to host my own cloud on a VPS like DigitalOcean or at home on my own Raspberry Pi. But I’ve been down that road before and know that I don’t want to be responsible for maintaining my own server.

GitHub to the rescue

After the failures listed above, I decided to give GitHub a shot. And I’m glad I did, because the process couldn’t have been much easier.

Using GitHub to host my Markdown files has required:

Perhaps I would not have been so quick to go with GitHub if I hadn’t already paid $19.99 for the Pro version of Working Copy. But the price of the Pro license is comparable to two months of Dropbox’s Plus plan, so this solution would still make sense.

Concerns

Despite being happy with my choice of using GitHub, I would be dishonest not to mention some concerns with this solution.

Syncing is not automatic

Syncing via GitHub is not a big deal. Just execute a pull or a commit and a push, and you’re good to go. That said, I could forget to push on one machine and then jump to another machine, unable to access the latest version of a piece of writing on that original machine.

Fortunately, I’m not working on any mission critical projects. Worst case scenario, I might take my iPad to the coffee shop and be inconvenienced because I can’t access the latest file version I edited on my Mac mini or Linux desktop. That’s a risk worth taking.

No internet

This problem kind of plays into the point about syncing not being automatic.

What if I’m out of the house with my iPhone or iPad and do not have reliable internet, meaning I can’t pull and update from my GitHub repo?

Conclusion

While my concerns are valid, I am fortunate that I am hardly ever without internet or in a situation where forgetting to sync would be detrimental. Also, I am not currently working on anything critical that could not wait until a later date, even if my anxiety makes me forget that at times.

Design as marketing

The following is from a discussion prompt for the class Usability and User-Centered Design, part of my technical writing certificate program via Oregon State University. I thought it was worth turning into a blog post.


For a couple months or so, I’ve been testing the Racket app via TestFlight on iOS. This is a short-form audio app (The founders often refer to it as the audio version of TikTok) that is finding its identity. As that identity changes, so does the UX. The branding (name, logo, colors) is the only thing that has been consistent over my testing.

The app has started to come together better and become more consistent as the team has latched onto an identity. This aspect is something that sometimes gets lost in the development of apps and sites: What is the identity of this service? What do we want people to feel? Also, how does our marketing affect our design?

Seth Godin often writes about how marketing is no longer isolated to one department. Now, every department of your company has a hand in marketing. Every part of your app/site/service is part of your marketing. This is something I wish more companies kept in mind. I go crazy when companies tell us they care about users and customers yet have horrible apps and sites that were obviously not developed with humans in mind.

Also, how does your company respond to criticism of its design? These days, I try to let companies know when I find errors on their sites or apps. For one, it’s good practice for technical writing and UX design. But also, I’m trying to pay it forward because as someone who’s dabbled in design, I know how easy it is to overlook little things when you’re trying to juggle so much. I feel a deeper connection to a company when it responds and acknowledges my complaints, and maybe even makes the appropriate changes.

Using Obsidian as a planner

In an attempt to find balance between the digital and analog in my life, I’ve inconsistently maintained a bullet journal for the last couple years. I initially fell in love with the analog approach to staying organized, but as time went on, I couldn’t help feeling as if something was lacking. Also, I’m accepting that, while I love the idea of writing more by hand and unplugging when possible, the practice is quite time-consuming and inefficient, especially if I plan to later type my writing to archive digitally or post online.

Recently I tried migrating my bullet journal practice to iA writer. While writer is a great app, it’s focused on one thing: writing. Unsurprisingly, this experiment didn’t work, so I found myself wanting something better. This searching is what led me to give Obsidian another shot, primarily as a planner.

I had also considered giving Notion another look but settled on Obsidian for two simple reasons:

  1. Obsidian is free.
  2. My files are saved locally, so I don’t have to worry if I need to work offline. (That said, I am using iCloud to sync between my Mac and iOS devices.)

Prerequisites

This post is not intended to serve as a tutorial for Obsidian itself, so readers are expected to have some previous knowledge:

Method

August 2021 is just around the corner, so let’s set up our planner as if we’re trying to get ahead for the new month.

I started my 2021 planner with a file I called 2021 Future Log.

Basically, I use an H2 for each month’s heading and then list things I expect to do in the appropriate months.

screenshot of future log Figure 1 - A screenshot of the future log

Next, I create another file for the week and fill it with some tasks I think I need to do in the next seven days. This one is called 2021-W32 (because 08.01.2021–08.07.2021 is the 32nd week of 2021).

Figure 2 - A screenshot of the weekly log

And then, I’ll make entries for the individual days of the week. I’ll start with Sunday with a file named 2021.08.01 Sun.

One thing I love about Obsidian is the ability to embed notes within notes. I start each daily note by embedding the monthly note and then the weekly note.

Since I put my monthly notes in one file (2021 Future Log), I want to make sure that I embed only the portion that pertains to August, as opposed to the whole future log. Once I embed my monthly note, I want to be sure to type a hashtag (#) after the title so that I get a dropdown with options for other headings to choose and embed.

screenshot of embedding tutorial Figure 3 - A screenshot showing how to embed a note within a note

I select the heading for August and then proceed with embedding the weekly note.

screenshot of embedded notes in daily note Figure 4 - A screenshot of notes embedded in another note


Note: Before we proceed with the rest of the template, let me explain why I like embedding the monthly and weekly notes into the daily notes.

With a traditional notebook bullet journal, to get the full picture, I would basically have to look at three different notes: the daily note, the weekly note, and the monthly note. I would have to search my index in the beginning of my bullet journal to locate these three notes and then read over them and combine in my head what needed to get done on these three different time spans. But, thanks to the embeddings, I have all three time frames on one page, in an order that makes sense to me.

Also, I love that, within my daily note, I can check off one of the events in my monthly or weekly note and the change will be made in the source note and in all other notes in which that note is embedded.


Now that my monthly and weekly notes have been embedded, I proceed with the rest of my template.

screenshot of complete daily note Figure 5 - A screenshot showing a complete daily note

Explanation of remaining headings

I’m using Agenda for events and tasks scheduled for a specific time. This is where I would usually put meetings.

I like breaking To-Dos into Personal and Work subcategories so that I can keep some separation between the two.

Notes is where I document things that happened that weren’t exactly planned or required.

And finally, Recap is a longer form journal entry–a reflection upon the day.

I repeat this set up for the other days of the week and then repeat the set up each week and month and, eventually, year.

Conclusion

The main reason I think this system can work for me going forward is due to the fact that Obsidian now has mobile apps, as opposed to my first run–in either late 2020 or early 2021.

Maintaining a bullet journal has meant trying to carry a notebook of some sort with me everywhere I went and then feeling lost if I didn’t have it with me. Because my cell phone is with me almost everywhere I go–the shower and swimming pools are a couple exceptions that come to mind–I don’t have to try to keep my planner with me; it already is with me, in my pocket.

During my last run with Obsidian, I tried to keep everything in the program, to grow my digital garden and my second brain. This time, I plan to keep my writing (blog posts, short stories, attempts at novels, etc.) out of Obsidian and in iA writer. In the short term, I plan to focus on making Obsidian work for me as my planner. If I can make that work, then I will consider branching out and throwing more at it and seeing what else can stick.



Subscribe
Via emailRSS

Contact
Email me