Folderbase is a repository of personal notes and documents that are unlikely to be shared with others, so you shouldn't need an Internet connection to access it. To launch it offline, you can move your folders to the root of a local server app running PHP 7.3+ (e.g. the htdocs folder for KSWeb on Android) and and navigate to the server address, (e.g. localhost:8080/folderbase/). If you want to put it online, you can follow the exact same steps; the only difference is that you'd be plopping the folder into a remote webserver root via SFTP or Git.

I use two apps for note-taking: Obsidian and Markor. Every now and then, I'll edit MD files in Sublime Text. All 3 apps work well for me, so I point them all to the main folder in which my text notes sit. The Folderbase web app is exclusively a 'view layer' for data sitting in my folders, with CRUD operations handled by a Markdown notes app (add/remove/edit text files) and a file manager (add/remove/edit image/media files).

Text files in one folder, images and other non-text assets in another. No database allowed. This structure offers maximum portability and eliminates vendor lock-in, as it doesn't require any kind of app scaffolding to navigate. If all you have are the raw files on a USB drive, your content will still be intact.

Even Stephen Ango, the CEO of Obsidian (defacto leader of offline note apps) advocates for a system that's based on files, and free of apps:

> File over app is a philosophy: if you want to create digital artifacts that last, they must be files you can control, in formats that are easy to retrieve and read. Use tools that give you this freedom. > @kepano

My files are organized in rough accordance with the Johnny Decimal system: all data stored in a maximum of 10 folders, each of which can have 10 subfolders, for a total of 100 folders. From a navigation standpoint, this means I can reach any file in the system with a maximum of 3 clicks.

This was inspired by reading about the design process of the Palm Pilot PDAs of the '90s, the earliest offline-first digital assistant. I prefer to navigate this way instead of using a search bar, which would the right UX option if I had thousands of files to look through. Having a spatial awareness of where my data sits gives me a feeling of comfort.

As much as I like Obsidian, its UI is designed for writing information and not really for referencing that information later. From a document browsing standpoint it resembles Sublime Text or Notepad++; a directory column on the left, and a wide editor/reading view on the right. I wanted something that resembled a 'desktop', or 'homepage', as offered in other (non-Markdown) tools like Notion.

Obsidian Workspace UI

Notion Workspace homepage (Source)

Folderbase is a personal, non-commercial tool that uses open-source libraries, so making the source code available was a no-brainer. The bigger reason for making it open-source is to allow anyone to extend it as they see fit. In general, FOSS makes it such that if the software stops being maintained (or stops meeting my needs), I can downgrade to an older version that still works, or better yet, I can implement fixes directly to the source code. This is what happened for me with Hotglue, a 10-year old WYSIWIG web editor whose runtime code needed some deprecated functions to be commented out in order to run on post-2015 versions of PHP.

I wanted to be able to write the code once and have it work on any operating system with a browser - my personal machine and phone (MacOS + Android) as well as my work laptop and phone (Windows 10, iPhone). If Linux is in the mix one day, it'll work there too.

Using web tools (HTML, CSS, JS, PHP) and using an app-ish browser window as the view layer is the only sane way to do this. Writing OS applications with native tools would require me to learn how to do that, 3 times over (C+ for Windows, Swift for Mac/iOS, Kotlin for Android). Even then, on platforms like iOS, a native app's source code would not be able to be distributed as open source

If I wanted to create a Pinterest-style moodboard by dragging some images into an Obsidian file, it will immediately resemble a stodgy Word document. But here's how it looks in Folderbase, with nothing other than a <div class="moodboard"></div> block enclosing the images.

Creating a Moodboard with drag-and-drop

I can't stand looking at browser chrome when using an app; it takes away vertical screen real estate and fills it with the distracting icons for all the other tabs I've left open! Mercifully, Chrome, Safari and Edge browsers all offer the ability to "install" a web app to your desktop. Once 'installed', the application launches in full screen, without an address bar or browser chrome, making it look and feel more like a native app (especially with the HTMX transitions). This requires a manifest.json file with links to an app icon image, as well as mobile and desktop preview images.

If your browser is Chrome, installing as a web app means that when you launch the app from your app drawer, it first loads a Chrome window, then a separate headless window containing the app. That's a bit awkward UX-wise; Safari and Microsoft Edge don't do this fortunately.

"Install Web App" dialog on Chrome

Obsidian's excellent out-of-the-box editing functionality, coupled with some CMS-friendly formatting options makes it a great 'edit layer' for Folderbase. For example, with a couple of setting changes, you can drag images into Obsidian and have them be saved in the 'assets' folder directly, with Markdown-friendly image links that display nicely in a web browser. This is a lot better UX-wise than saving to a generic 'download' folder, moving the file to 'assets' and then painstakingly adding a Markdown link to the file

The writing experience in most Markdown apps is fine; the reading experience however is not. Obsidian for example shows your document in a boring top-down view with narrow margins, pretty much exactly in the layout you used while wroting it. If you use a paid service like Obsidian Publish to put it on the web, it will use the same display theme as in the app -- boring! There's so much available screen real estate, but the Markdown format confines you to single-column layouts.

Not on Folderbase though. With a simple code block I can change the page layout into multi-column grid that supports 4 columns on desktop, and folds down to 2 on mobile:

<div class="grid-4">

<div markdown="1"> // Column 1 start

Column Content (text/image/audio/video)

</div> // Column 1 end

</div>

4-column grid layout on mobile

The same applies for CSS columns (separate from CSS Grid). By enclosing paragraphs within a code block like `

When clicking through to a new page, there was an unsightly white flash in the browser as the server switched from displaying Page A to Page B. A proper web application would have a system of views and URL routing that would smoothly load in the content of a new page without refreshing the entire browser viewport.

For those building framework-less non SPA sites, there are ways around this. You could use client-side solutions like smoothstate.js, BarbaJS, or the SWUP library. Of these, I'd only ever gotten SWUP to work, and even then it didn't have the smooth effect I expected.

HTMX to the rescue. I'd taken a Javascript class some years ago and had learned about AJAX/XHR requests, a way to load content into a web page without a full page refresh. Unfortunately, the amount of code required for a single XHR request was a hassle to type out. HTMX wraps all that up into a single property hx-get, which can pull in the URI of the linked page via a Pico object page.url. I added in an optional attribute: hx-replace-url. This ensured that page changes would update the browser history, and that the breadcrumb navigation I had set up would reflect the correct values for "parent page" and "child page" when internal links were clicked.

I am not a developer, so building this out required a lot of trial and error, in addition to hunting through closed or abandoned tickets in the Pico CMS Github.