Text Editing in Athens

[jsmorabito]

Higher level conversation about plans for the text editing experience in Athens.

Notes

• might want some combination or the option to choose between markdown editing style and wysiwig

Timeline/Priority

1. markdown editing
2. wysiwyg (goal?)

References

• Obsidian (markdown)
• Roam (markdown)
• Microsoft Word/ Google Docs (wysiwyg)
• Typora
• Ulysses
• iA Writer (markdown)

[tangjeff0]

Notion has both Markdown and Wsiywig shortcuts

[Limezy]

For me the best in town is definitely Typora. I would love to have a "Typora feel" inside Athens.
As I already expressed it in a feature-request discussion, I have a strong feeling we should somehow make a relationship between the outliner mode, where we can basically only see bullet points embedded inside eachother, and the "markdown // nice document" mode, where the hierarchy is no longer bullet points levels, but headers, paragraphs, sentences, bullet lists.

I keep seeing youtube videos about people telling they are moving to Obsidian eventhough the prefered Roam, just because Obsidian can produce something a bit different than pure endless bullet point lists. Let's make both at once if possible !

1st : messy bullet points everywhere, I organize my ideas and I write stuff everywhere etc...
2nd : my bullet point hierarchy can automatically become a "nice document" hierarchy with headers , paragraphs... I just have to define where is the "ground level" i.e. where is the paragraph level in my stuff
3rd : I can quickly and easily export my final documents as .md

That would be great and answer the needs of a lot of Roam users currently switching to Obsidian

[Limezy]

I'll definitely have a look as soon as it's released

EDIT : @tangjeff0 @shanberg sorry I moved all my comments below since github was hiding our whole conversation.

[tangjeff0]

This is very helpful, thank you.

[Limezy]

With great pleasure. I can't really code but I can help thinking about usages / UX design :)

[shanberg]

How about when folks only need one or two levels of headings, such that the flow is H1 > P, or H1 > H2 > P?

Athens block content is multi-dimensional in a way that Markdown is not: In Markdown, everything except bullet lists live on the same vertical line. In Athens, you could indent an H2 underneath an H1, but Markdown doesn't have a natural way to represent that. I could be wrong, but I don't think they're fundamentally isomorphic.

[Limezy]

EDIT : My reply moved below

[Limezy]

Hi @tangjeff0, I've tried the "Copy Unformatted" new function. Great to see markdown support slowly coming into Athens !

Few feedbacks :

1. Once a block or group or block is selected, I find it rather unintuitive that if I don't right clic exactly on the bullet, my selection is then lost. For me, the full blue surface should be right-clicable
2. Same spirit, If I select more than one bloc and I right-clic on a sub-block, looks like I'll copy only that sub-block but the whole selection is selected
3. Sounds really strange to "Copy Unformatted" something but keep markdown headers ? For me, if you "Copy Unformatted", that should remove anything but plain text, that is no headers, no bold, no italics, no highlights, no bullets, nothing !
4. I would rather add an option in the same right-clic menu, labled as "copy as flat markdown", which would keep the headers, bolds, italics, highlights, but remove the bullet points for headers + paragraph level (and keep them underneath)
5. And another option (which is the current option when hitting ⌘+C), labeled as "copy as outlined markdown", which would keep all (headers, italics, highlights, bullet points...)

I'll make a few mockups below

View in Athens editor

Paste result after "Copy as unformatted text"

Paste result after "Copy as flat markdown"

Paste result after "Copy as outlined markdown" (the current default behaviour)

Does that make sense ?

[Limezy]

And on the WYSIWYG side, we could think the exact same way, having either a "flat document view", or "outlined document view" (Athens is currently only supporting the "outlined document view").

That would switch between this view : (outlined document view)

And that view : (flat document view)

(Mockup made with Typora)

Last but not least, and then I promise I'll temporarily stop flooding this discussion, a few comments about managing headers :

When I'm typing in a H1 block, I would expect that :

• Typing another block below at same level would by default be formatted as H1
• Typing another block underneath would by default be formatted as H2
• And so on, with H2 > H3, H3 > Paragraph, Paragraph > Bullets
• Doesn't mean we couldn't have an H1 under an H3, but would just allow to format very fast a kind of standard H1 > H2 > H3 > Paragraph > Bullets structured document

[Limezy]

@shanberg
How about when folks only need one or two levels of headings, such that the flow is H1 > P, or H1 > H2 > P?
Athens block content is multi-dimensional in a way that Markdown is not: In Markdown, everything except bullet lists live on the same vertical line. In Athens, you could indent an H2 underneath an H1, but Markdown doesn't have a natural way to represent that. I could be wrong, but I don't think they're fundamentally isomorphic.

@shanberg I fully agree with you that an outliner software and a markdown representation (or any traditional document formating) are not isomorphic things. However, I still believe there is a kind of natural relationship between outlining bullet levels and document formating hierarchy.

I also strongly believe that a pure and endless bullet list, although it's pefect for frictionless and quick dropping of your ideas, or raw drag-and-drop / reorganizing of your thoughts, is not confortable to read nor share, and difficult to process in the mid stage to a finished document.

I don't know how many dozens of youtube videos I've seen where people say that even though they liked better the Roam idea collecting and connecting process, they moved to Obsidian because that was a tool where they could process "human readable" documents / evergreen notes etc... Athens will soon face the exact same comments by its user, unless we find a way to "do it both", which would be for me (but this is again nothing more than my humble opinion) :

1. An outlining mode, Roam-flavoured, where you can basically throw all your thoughts, give them a kind of bullet hierarchy, drag and drop your bullets etc...
2. An outlined document mode, a bit more Markdown-flavoured. Keeping the flexibility of the drag and drop, the hierarchy collapse, the "zoom on bullet" things, but also including some kind of quick and helping markdown features, based on a natural hierarchy (such as H1 > H2 > H1 > P > Bullets).
3. A flat document mode, fully Markdown-flavoured (Typora inside Athens, let's call it)

With regards to your comment about one or two levels of headings, I don't think that would be a problem at all :

• Let's say you open a page in document mode
• You create a H1 line
• You hit enter + tab, the system shows you that you are in H2 mode for that new line
• You don't want H2 ? No problem, hit tab again, the line doesn't move but switches to H3 mode
• You don't want H3 ? No problem, hit tab again, the line doesn't move but switches to P mode

I agree that at some point building some helping tips like this will necessarily induce a little bit more rigidity in the system by introducing some kind of basic templates (like the hierarchy H1 > H2 > H1 > P > Bullets). But I think that one of the mistakes of Roam is to take as a basis that users are against any type of rigidity or friction. At some point, having a little bit of pre-set structure will make you go faster.

Not even mentioning that the reference hierarchy could be a setting, Athens level or Page level.
Anyway, always interesting to discuss about the text editing in Athens, which is in my view way more important than throwing at it plenty of gadget features such as pomodoro timers, bells and whistles, excalidraw drawings and so on.

[lobre]

I personally tend to always strive for simplicity. While I totally understand the ideas behind those document vs outliner modes, I am doubtful about the possible added complexity if both are implemented.

I don't know how many dozens of youtube videos I've seen where people say that even though they liked better the Roam idea collecting and connecting process, they moved to Obsidian because that was a tool where they could process "human readable" documents / evergreen notes etc...

That’s totally true, I have also seen those videos and to me, the overall question is always about whether the application is an outliner or not.

An outliner, by definition, is a "computer program, or part of a program, which allows its user to create and edit a hierarchically arranged outline of the logical structure of a document".

So IMHO, the core question is about what Athens really is, and what it wants to become. As of now, I think it has always been more of an outliner than anything else (following what Roam does). I haven’t participated in recent calls or discussions about the roadmap so I don’t know much about the ambitions but if this outliner constraint is dropped, that could dramatically change the direction of the project.

I see the markdown integration as a helper. Most tools emit or receive markdown nowadays. So having functions to import some bits of markdown or export a page in markdown can definitely be a time saver. But I don’t think there should be much effort trying to find the perfect relationship between markdown and nodes as designed in Athens. They are simply not the same and I am not even sure that one is a superset of the other. To me, markdown should stay a side feature that improves interop, but not be part of the core system (as opposed to what is done in Logseq for example).

And when I open up Athens to write, I’d love to keep having a super simple writing experience. I don’t want to ask myself too many questions such as: "am I going to write a proper document, or should I just quickly drop some notes in the outliner mode?". I just want to start writing.

Maybe at some point, I will have a page that looks like a finished document, and then maybe simply having an export to a more vertical/flat format (such as markdown) could be sufficient. If I really want to start writing a flat piece of document from scratch, I would probably not use Athens because I think it hasn’t been designed exactly for that, and it is not where it shines. To me, Athens is really for thought connections and growing/living knowledge.

At least, that’s how I see it. Maybe I am missing something, but I just don’t envision a simple way to have this document experience in Athens. And I like simple tools 😃.

That’s my two cents.

[shanberg]

There may be a conflict between the pure writing aspect of Athens and the knowledge-graph aspect. The synthesis of traditional writing creates a a few data-rich nodes in the graph, but in a way that's hard to decompose. Outlining creates many nodes, but with a clearer relational structure.

Maybe there's a better way to visually represent an outline that looks and feels and types more like a plain Markdown experience.

[Limezy]

The synthesis of traditional writing creates a a few data-rich nodes in the graph, but in a way that's hard to decompose

@shanberg I agree, but by just automatically outlining headers > paragraphs > lists we would already be helping a lot the user to start outlining a standard-formatted text. And even if that leaves some pretty big blocks populated with the former paragraphs of the original text, that would be really easy for him to pick any part of the paragraph he wants, and hit "enter" to make a new block and start splitting the paragraph into structured outlined ideas.

[Limezy]

Is being only an outliner a constraint ?

@lobre to me, the overall question is always about whether the application is an outliner or not.

Yes, I fully agree with that. Very long videos just to explain that Roam is an outliner, and that they actually need a Markdown editor (with a little bit of links / backlinks).

@lobre As of now, I think it has always been more of an outliner than anything else (following what Roam does). I haven’t participated in recent calls or discussions about the roadmap so I don’t know much about the ambitions but if this outliner constraint is dropped, that could dramatically change the direction of the project.

... but I kind of disagree with this. I don't think that just "being an outliner" is and will ever be part of Athen's core values. What seems to me to be the deep core of Athens is to be a knowledge graph, aka a piece of software that eases the linking between different writings and thoughts. It is a fact that Athens, as primarily an open-source clone of Roam (but I'm sure this won't last very long, see how Logseq is already diverging paths with Roam), uses the outlining principles as its primary way of inputing / organizing text. And this will remain the first and preferred text input option for sure. And it's a good thing. Just like you, I feel how great is the simplicity of an outliner to input text and quickly pre-organize my thoughts.

However, I believe that being an pure outliner (that is, not providing any other way of dealing with text input / manipulation) is not a required constraint for what Athens tries to achieve.

About having a "document mode" as a feature (plugin or core), to keep users longer in their writing process

@lobre To me, markdown should stay a side feature that improves interop, but not be part of the core system (as opposed to what is done in Logseq for example)

I don't know whether Athens will deal with parallel ways of editing / importing / exporting text as plugins or part of their core, but not dealing with them would be a mistake in my opinion. And being a core feature doesn't mean you have to use it, especially if it's a parallel mode. A lot of Obsidian users never trigger the rendered mode and just use the raw markdown mode, for instance.

If I try to quickly sketch the main steps of a text-based document production, that would be :

1. Gather and pre-sketch
2. Connect & organize
3. Pre-sketch your writing
4. Polish both content and look

Obviously it's not as sequential and a little bit of these steps is always made in parallel.

There is no question that the outliner + link / backlink combo of Roam & Athens are perfect for the steps 1 & 2.
But the pity is that most people will quit Roam or Athens to go to Obsidian or somewhere else for the step 3, and by consequence are loosing a big part of what the connection graph could provide them while starting to sketch there writing !

Of course, Athens will never be the tool for the step 4, there are some specialized softwares for that (MS Word, Latex...). But a well-done "document" mode would help keeping users a little bit longer in the process, and by such helping them taking fully advantage of their connections and links while starting the real writing.

About the necessary mapping between outliner mode and document mode

@lobre I see the markdown integration as a helper. Most tools emit or receive markdown nowadays. So having functions to import some bits of markdown or export a page in markdown can definitely be a time saver. But I don’t think there should be much effort trying to find the perfect relationship between markdown and nodes as designed in Athens.

As you said, markdown import / export is becoming a must for every text manipulating tool nowadays.
Whether it is for import, export or having a document mode, the result will be the same : you absolutely need a mapping. No choice !

The quick and dirty usual mapping between an outliner and markdown is to just keep everything as nested bullets. However,

• This only works for md export.
• Nobody writes any long document with crazy numbers of nested bullet points
• If you try to build a md import, you'll loose basically all headers information

This is why I was advocating for a more organic approach, that simply considers that in a sense a H1 is a block that embeds an H2, which is himself a block that embeds an H3 and so on. And then the mapping for lists is obvious and easy.

And then there is the mapping for the links

• Links & tags ? Just keep the [[usual]] #syntax
• Blocs quotes ? I don't see what is lost if replacing them by line quotes ?

[lisachev]

I would be happy if I can pull the blocks I need to the right pane, rearrange them to build a story line and then export as md, where blocks are divided as paragraphs. This would be a 95% correlation with what I do at step 3 in your convention.
Step 4 would involve me reading the end result, formatting, putting explanatory headings for the story flow and adding data back to the graph in the meantime.