Bike file formats

Bike Outliner
1

I’ve been accumulating notes on Bike (in Bike, of course) but figure I better get them off my chest. First, on file formats.

Text files (save as .txt)

I love the simplicity but I really wish it used tabs instead of spaces. I know tabs-vs-spaces is a religious argument – but I think that’s in programming language contexts. As a file format for an outline, tabs are a natural fit, and spaces are not. You can type literal spaces in a row in Bike, but you can’t type tabs, because in Bike, the keyboard Tab key always means “indent this row one more level”. Bike won’t even let you paste a tab character into a row. (Not complaining about that, just pointing out that literal \t characters seem like they can exist in a Bike outline.)

Tabs would be more like a word processor’s tab stops than a plain text editor in that way. When you’re using Bike (or any proper outliner), the leading indentation feels like tab stops, not spaces. I think one reason why the tabs-vs-spaces argument for programming source code is neverending is that in a text editor, leading tabs and leading spaces more or less feel the same. (That said, I will admit that I’m a tabs guy in source code.)

By using spaces, you’re inviting arguments about how many spaces should be used. Some people might say 2. Some might say 8. If you use tabs it’s clear: each \t = 1 level of indentation. Done. Nice and clean, nothing to argue about.

I know it’s a bit of a contrived example, but consider that a row can start with literal spaces. How would that work with the current text export format?

Another question: what are the advantages, as a users, to using Bike’s native .bike format instead of saving all my Bike outlines as .txt files? It is 100% obvious that Bike should export to text files, of course, but should it be able to open them and treat them as Bike files? There’s a part of me that thinks Bike should be able to export and import text files, but when importing/opening one, it should become a new unsaved .bike file. I’m not sure though.

Bike/HTML

I’d be OK with the native Bike format being a black box, honestly, as long as it has open export formats. I think it’s kind of neat that the native format is just HTML though. I’m not quite sure where you’re going with the ID values, or whether I should care how they’re generated, but it is a very nice bonus that you can just open a .bike file in a web browser and it renders as a list.

Are you planning to support embedded images? If so, how would that work? I presume you’d have to switch to a package format, like RTF vs. RTFD for TextEdit files with embedded images. My guess is that you’re thinking of Bike as more like a plain text editor, with no embedded images.

1 Like
2

Is the use of spaces a recent change ?

My impression was that earlier builds were (like TaskPaper) copying and writing out tab-indented text outlines …

3

Thanks and good to hear.

I think it’s always been plain text indentation with spaces in Bike, but I’m happy to change to tabs. Matching TaskPaper makes sense. I think Bike’s text export came out of some debugging code and I think there I was using spaces and just didn’t think too much about it.

Another question: what are the advantages, as a user, to using Bike’s native .bike format instead of saving all my Bike outlines as .txt files? It is 100% obvious that Bike should export to text files, of course, but should it be able to open them and treat them as Bike files? There’s a part of me that thinks Bike should be able to export and import text files, but when importing/opening one, it should become a new unsaved .bike file. I’m not sure though.

I like that Bike can round trip plain text files, and will keep that, but it’s a lossy process and I expect it will be become more lossy over time.

The two advantages today of using Bike format is that expand/collapse state will be remembered and bike: links will work between save/load. Plain text format can’t store IDs and those features rely on IDs. In the future rich text formatting will likely be lost and your file won’t work right with scripts/plugins that expect support for persistent metadata.

I need to put up an alert on first save to indicate that plain text is lossy. My expectation is that almost no one will use plain, but for the few people that do use it it will be important. Also it’s easy enough to support because I need to support the same logic for copy/paste of plain text.

I really like the HTML format, but it’s not the fact that your outline can become a web page that’s most interesting to me.

Instead what I like is that it’s an open extensible format with lots of existing tooling. I want technical users to be able to easily dig into and generate their own Bike files. I like the various scripts and workflows that have come out of TaskPaper, but there was always the difficulty of parsing and writing valid TaskPaper formatting, and there was no place for scripts to store any metadata. I think HTML addresses those problems nicely.

Bike 1.0 isn’t going to achieve this, but a big goal with Bike in the future is plugins and scripting.

ID’s are just unique strings. Bike generates them for you, but you can also edit your Bike file to use your own ID as long as it’s unique. Right now ID’s are used to remember expand/collapse state and serve as targets for bike link resolution. In the future I expect scripts and plugins will often use known unique ids to perform tasks… for example an “Archive Done” command would search for or create an item with id=“archive” and move items there.

I’m still not sure on this. I would like to support images… I think they would be less like images in a WYSIWYG word processor and more like a link with a preview thumbnail. Anyway sorta on my list, but lots of other stuff before it, so haven’t though through many of the details.

2 Likes
4

And one of the first wins from that, for me at least, is that the ‘invisible’ layer can contain unique ids, providing, amongst other things, targets for local and inter-document hyperlinks.

5

ID’s are just unique strings.

They’re just unique per-document, not across documents, right? I almost didn’t even ask this given that the ID strings are only 3 characters in my own Bike files.

1 Like
6

They are only unique per document, but the document’s root ID special and initialized to a UUID. So to point to a specific item you can combine the UUID root with a locally unique item ID.

So you can use root ID for global uniqueness, and then item ID to point to a specific item. That’s how bike links work. So for example if you Edit > Copy > Copy Link you will get something like this:

bike://f2QhwMmN#UP

The item ids are short to start, but will get longer if there are collisions.

Edit: The root id isn’t UUID. It was at some point but those seemed unnecessarily long for Bike’s purposes. The root ID’s are long enough that you should never see random chance collisions when working on your files. At the same time there’s always the possibility of collisions no matter how long the root ID is since a user can duplicate a Bike file in the Finder. The general goal is to have links that won’t break on an individuals computer.

1 Like
7

I’ve been looking for documentation on the .bike format, what tags and attributes are allowed. I’m hoping that one might even be able to extend the format but adding extra tags or attributes or at the very least embed comments that get retained by bike – but such extension mechanisms are not currently supported from what I can tell.

8

I don’t have much documentation other than to say it’s a subset of HTML.

Bike should retain/round trip:

  • data-NAME attributes/values on each <li>.
  • contents of <header>

As far as file format, at one point I expected <li> to contain arbitrary “content” elements. <p> being the default, but also supporting <hr>, <h1>, etc. I am no longer expecting to do that. Instead Bike stores content typing information in a data-type attribute on the <li>.

If you describe what you need/are trying to do, then maybe I can make a suggestion or changes things so that Bike will retain more.

1 Like
9

Thanks for your quick reply, Jesse. My immediate goal is make round-tripping between Obsidian and Bike more easy. I love Bike but I also love writing in Obsidian, which happens primarily in Obsidian-inflected markdown. I’ve not worked how my goal impacts what I’d love to see in the bike format itself, but when I do, I’ll write more here. Hoping that my telling you my desire for Obsidian-bike interop gives you some useful context.

10

It does, thanks.

I would like to eventually add .markdown as another supported format (probably not for a while, probably somewhat lossy), next to .bike, .opml, and .txt. Your project will be quite useful to me as an example of one way to do that.

I expect you are aware, but the latest preview (1.13) releases of Bike adds row types, many of which map pretty directly to Markdown. So if I were you I would use those mappings.

On place where the mapping is not direct is headings. Bike has just a single heading type, instead of h1, h2, etc. The thought is you could map those headings to outline hierarchy.

Anyway, I’m interested in this project. Would love to hear how it goes and where there are problems that maybe I can address in Bike’s code.

3 Likes