Intro and Philosophy Rant

  • Some years ago, my coworker introduced me to this great online tool called Notion.

    • I instantly fell in love with it. I used it as a personal knowledge management (PKM) tool from that day forward, and I swore by it.

      • I used it as:

        • a journal

        • a project tracker

        • a to-do list

        • a way to bookmark websites and keep notes on them

        • a recipe book

        • a code repository

        • a gallery

        • a reading tracker

        • and a bunch of other things too

      • But then my interests started drifting elsewhere.

        • I became an advocate for open-source software (OSS), which makes sense - the software that I teach for a living is open-source. I became indoctrinated by the philosophy of open code, open internet, and an open world. That is to say, a collaborative effort, a global community where everyone can contribute however they can/want.

          • I no longer believe in the rockstar, spearheading, enterprising, “genius” individual that becomes the figurehead for whatever agenda they’re pushing.

            • I believe in teams.

            • I believe in communities.

    • Notion is not OSS. It is proprietary. And there’s nothing inherently wrong with that! Their team made a great product and they deserve to earn money off of it. A lot of enterprises use it as a collaborative alternative to Google’s suite of cloud-based office tools.

      • There are downsides to Notion. Primarily, the three biggest downsides to me are:

        • 1. Not OSS. If I wanted to, I couldn’t open up the hood and stare (unknowingly for sure, I don’t even know what their techstack is) at the underlying code. I couldn’t reach in and pull on wires and make changes, for better or for worse.

          • Sidetracking for a moment: I believe strongly in the Right to Repair. If I own something, I should be able to take it apart and fix it myself, if I really want to.

            • However the current trend with modern tech is to discourage self-repair as much as possible.

              • What are you doing with that screwdriver? Put that down and take our device to our nearest Approved Technician™️ so that they can tell you that you should just throw it away and buy our latest shiniest model instead.

            • Does this apply to online subscription-based software? Debatable.

        • 2. Online-only. This has been a major source of complaints from the Notion community. Notion is hosted on Amazon Web Services (AWS) so all of your information is on Amazon’s servers. Not yours. Never yours.

          • This causes friction when trying to access your information. You need to have a fast enough internet connection, and you can’t synchronize your data to your machine in order to have it offline.

          • This didn’t initially bother me. To be sure, Amazon and I are not friends. But a lot of websites are hosted on AWS, so this point wasn’t the thorn in my side.

            • The trouble started when Notion all of a sudden became noticeably and painfully slower.

              • Now this can be caused by many things.

                • Could be AWS was having a hard time. For a while.

                • Could be Notion’s userbase grew too quickly for Notion to scale out (that is, provision more resources - CPU, RAM, etc, in order to meet traffic demand)

                • Or it could be that Notion, not wanting to pay so much overhead, lowered their amount of resources from AWS, while still charging the same amount of money from their subscribers.

                  • Who knows.

                    • Not me.

          • For the sake of transparency, the website you’re currently reading from is hosted on Gitlab, which is primarily hosted on the Google Cloud Platform. Cave on Mars and my Brain Pins are hosted on Microsoft Azure.

            • If I owned a machine I wanted to keep running 24/7, I would host them myself, but alas. Electricity bills and that.

        • 3. Notion AI. This was a divisive addition in the Notion community.

          • In response to the community’s speculation, Notion HQ released a statement promising that no one’s content would be used to train the AI.

          • Man they really pushed the heck out of that AI.

            • You couldn’t make a new paragraph without it asking “Would you like to use Notion AI to help you write? :) Only $9.99 a month!”

              • All of a sudden, my desire for an open-source, offline solution bloomed.

  • You know what makes the world beautiful? Alternatives.

    • Let me introduce you to my new favorite website: AlternativeTo.net

      • You got software that’s mildly bugging you? They’ve got thousands of crowdsourced alternatives, with user reviews and recommendations.

        • And a lot of those user reviews are great. In general, your average review is informative “good alternative, it has more features” and so forth.

          • But my favorite review that I’ve seen was calling out the toxic development community of a specific piece of software. “Avoid at all costs. If you go to their forum asking questions, they will be extremely rude.” Just look at the negative reviews on this one.

            • I don’t care how good your software is - if you’re an asshole, I’m avoiding your software.

              • And this is why the user reviews are so great!

      • And in my personal quest to become more open, I’ve found open source alternatives to the software I used to use.

        • So I put in Notion, right? Obsidian comes up, I’ve seen it before, it’s pretty decent. Proprietary though, so I’m not interested.

          • And then there was Logseq.

            • Oh Logseq.

              • You’re open source?

                • Offline??

                  • I…

                    • 🥺

            • To be honest, I tried Logseq for a couple days and wasn’t totally sold. I was still working in the mental box of Notion’s databases that I was so convinced that I needed.

              • So I tried AnyType, which is specifically marketed as an open-source alternative to Notion.

                • But then I kept finding myself going…

image.psd.png [image id: A meme. Shutterstock photo of a woman oggling a passing man as another man, presumably her lover, has his arm around her. The woman has hearts over her eyes and “Rae” over her head. The passing man has “Logseq” over his face. The spurned lover has “Anytype” over his face.]

            + Listen, AnyType is fine. But it's no longer for me. I'm a Logseq goblin now.

Logseq

  • If you’re wondering why there’s so much bulleting and indentation going on on this page, you can blame Logseq.

    • Each bullet has its own ID that you can integrate your notes into other pages, which is using the atomic notes/Zettelkasten method of note-taking.

      • Seriously, try clicking any bullet on this page, and you’ll be focused on only that bullet and its descendants, and the URL will have a special ID. It’s great for focusing on a topic.

  • Logseq has a built-in daily journal.

    • Does that sound great?

      • I actually fucking hated it.

        • I avoided it as much as possible.

          • I keep a paper journal, I’m not going to do double work.

          • Don’t do what I did.

            • Get used to the daily journal as quickly as possible, because now? I live on that shit. That’s where I put everything. Is it a mess? Kind of. Does it work? YES.

  • You can just tag things.

    • You can tag things as much as you like!

    • Now click on that tag and you’ll be taken to a mostly-blank page, but it will show all the times I used that tag.

      • I dunno I think that’s fucking great

      • It’s how I keep track of random fleeting thoughts

      • It’s how I keep track of topics to talk about in therapy

      • It’s how I keep track of art-ideas

        • All of these are going to be blank because of course I’m not making any of that public, you weirdo.

  • So now Logseq is my PKM (from the intro, that was a while ago, Personal Knowledge Management)

  • But Logseq has one glaring flaw:

    • It’s offline.

      • Yes I know, that was a selling point for me, so how could that be a flaw?

        • Well, it’s a double-edged sword.

          • It lives on my PC, and only my PC.

            • How do I sync my thoughts to my laptop? My phone? My other phone? My work laptop? My tablet? My other PC at work?

              • I’ll tell you how.

Git

  • Git is a tool primarily used for synchronizing development codebases between collaborators. It’s used in companies, but it first started out in the open-source circle.

    • You’ve made some code and you want your friends or colleagues or whoever to be able to contribute.

      • How do you get it to them?

        • Zip up the files and email it to them?

          • But what if you make changes in the meantime?

            • Zip it up and email it again.

              • But maybe they’ve already opened the first zip file and made some changes.

                • Now they need to manually check the differences and merge the new code in and-

                  • Doesn’t that sound like a hassle?

                    • Now imagine a company of hundreds of developers doing the same thing with millions of lines of code.

    • The cool thing about git is it doesn’t need to be code. You can sync anything to a git repository (repo)

      • Of course, depending on where your repo is (usually it’s Github, but Github - shockingly - isn’t OSS. Gitlab is though!) there’s gonna be a storage limit for free accounts, so big things like images and videos aren’t recommended.

        • But text-based things that can fit into text and markdown files are perfect!

          • Which is why this website is hosted on Gitlab :)

That’s enough wind-up, let’s get to the steps.

The Steps

  • I hope you’ll forgive me for writing this like a step-by-step tutorial - it’s what I do for a living.

Hey by the way, all of this costs nothing

  • well, okay, the Tasker Android app costs like one-time $4, if you want mobile device automation

Install Logseq

  • There’s a handy download button on the Logseq page. It’s available on most platforms - even mobile!

  • When you run Logseq, you’ll want to make a folder to store all your Logseq files. All of mine are in a folder called second-brain in my documents folder on my PC.

    • These are the files that I want to synchronize to all of my different devices.

  • Now add your thoughts to Logseq to your heart’s desire, with the security that you and you alone own your data!

  • But you want to be able to access your data on your other devices. So the first thing you should do is click on the three dots in the top right ... and choose Settings

    • Click on Version control

      • and then toggle Enable Git auto commit to true

        • 60 seconds is the default, which is fine for our purposes.

          • This means every 60 seconds, Logseq will automatically “commit” (kind of like save) our changes to a secret folder, which we’ll get in the next step.

Install Git

  • Git is a command line tool, so we’ll be using the terminal. That’s right, we’ll get to feel like a hacker.

  • Download and install git

    • If I remember correctly, the options in the install are kind of a lot. The default settings should be fine for our purposes.

  • Once you’ve got it installed, open a terminal in the directory you have your Logseq files

    • Windows tip: If you open the your Logseq directory in your file explorer and type cmd in the address bar at the top, it’ll open a terminal pointed to that directory

  • Type git init

    • This initializes (init) the directory as a git repository and adds a .git folder which tracks all changes in the folder automatically!

Make a new project on Gitlab

  • Create an account on Gitlab and make a group. You can call this anything. I called mine cave-on-mars (that’s where the cave-on-mars bit in this page’s URL comes from)

    • Make a new blank project on Gitlab. I called mine second-brain (and that would be where the second-brain bit in this page’s URL comes from).

      • Keep it private because otherwise all of the content of all of the markdown files would be readable. The journal, everything. In this case, don’t be so open.

        • All of the default options are fine for now. Put in a name for the project, and then click Create project

Push your Logseq files to Gitlab

  • When you made that new project, Gitlab should show you some lines similar to this:
cd existing_repo
git remote add origin https://gitlab.com/your-group-name/your-project-name.git
git branch -M main
git push -uf origin main

+ Copy those 4 lines (yours, not mine) and, making sure that your terminal is still pointing at your folder you have your Logseq files in, paste them into the terminal.

  + Wait a minute or two, depending on how many files you have.

+ If all went well, you should now have all of your Logseq files on Gitlab! Now your files are stored in a private repository on the internet.

Synchronize those files across your different devices

  • Look at your project on Gitlab. You should see a Clone button off to the right. Give that a click and it’ll pop up for some options. Next to “Clone with HTTPS” click on the copy URL button.

    • This is your git clone URL. You can now use this URL to “pull” (essentially, download) your files from the repo onto any device.

  • Install git and Logseq on whatever device you want to sync to. Don’t forget to enable Git auto commit in Logseq on this device too. For now, and for simplicity’s sake (it gets a bit hairy with mobile devices) I’ll talk about how to do it on another PC

    • Open a terminal on your PC, and navigate somewhere where you would want your Logseq folder to be on that machine. Might I recommend the documents folder?

      • In that terminal pointed at your documents folder, type git pull and then paste in your git clone URL.

        • git pull https://gitlab.com/your-group-name/your-project-name.git

        • It will “download” your Logseq files to a new folder with the same name as your Gitlab project, your-project-name in the case of my above example.

          • I say “download” with quotes because it’s more like a two-way street. The files are downloaded, but it also has a link to the repo so you can git push or “upload” files right back!

  • And with that, you’re now synchronized!

Syncing to mobile devices

  • I’ve never used iOS, so this video is your best bet if you have an iPhone.

  • For Android, you’re gonna need:

    • Tasker (I recommend the paid version)

    • Termux (get it from F-Droid, NOT the Play Store)

    • Termux: Tasker (same as above)

    • this guide

      • good luck!

        • seriously tho, if you need in-depth help with this one, you can reach out to me

Publish Logseq pages to a website like this!

  • So maybe you’ve gotten this far and you want to make some pages of your private Logseq instance public.

    • The first thing you gotta do is give whatever pages you want to be public the following property:
public:: true

    + just pop this line at the top of every page you want to be public in Logseq (for an example, you can see it at the top of this very page!)

+ Next, we gotta set up Gitlab Pages

  + Looking at your project on Gitlab, in the left menu, go to Deploy > Pages

    + Select your build image:

      + `ghcr.io/pengx17/logseq-base:master`

      + check the box, click next

    + Click next so you're on step 3, and add the following steps:

      + `mkdir public`

      + `mkdir public/.nojekyll`

      + `mv publish.mjs /home/logseq/publish.mjs`

      + `cd /home/logseq`

      + `"xvfb-run node /home/logseq/publish.mjs -p $CI_PROJECT_DIR -t $CI_PROJECT_DIR/public/build_trace.txt -o $CI_PROJECT_DIR/public"`

    + Save your changes, wait roughly 3 minutes, and then visit your URL. It'll be something like:

      + `https://your-group-name.gitlab.io/your-project-name`

    + But now we have a small problem - this will publish the website every time you make a "commit" to your repo. Which, according to Logseq, is every 60 seconds while you're working. This puts a lot of strain on Gitlab, so let's do them a favor and set up a scheduler.

      + On the left menu on Gitlab, go to Build > Pipeline schedules and click on the New schedule button in the top right.

        + Set up an interval pattern - I set mine to only publish at noon daily, and even that's maybe too often, since I don't update this website often enough, but that works for me.

With all of that done, dust your hands off and get a congratulatory beverage. You’ve got a fully-automated open-source PKM repo, with the option to automatically publish public pages to the internet!