Edit Oops… just realized this won’t work for anyone until I post a new version of Birch that includes some new API used by this package. Will post that tomorrow.
I’ve just posted a package for authoring Markdown in Birch:
It’s a work in progress, but I hope it will serve as an example for how such a thing might be done in Birch.
The approach is very simple. For each Markdown type that I want to support I’ve added a command. For example I have commands for “Make Heading”, “Make Code Block”, “Make Ordered List”, etc. Each of these commands simply sets the data-type of each selected item. This package also adds some styling rules so that items where data-type="heading" are styled with a brighter color for example.
I also have a “Copy as Markdown” command that converts the content of my outline to Markdown text, which I can then feed into a Markdown processor to generate the final users guide.
There’s still lots to be done to make this user friendly, but I think the basic approach is sound. If you do decide to use this package make sure to checkout the included keymap…
You aren’t likely to want to do Command-Shift-P and then search for each “Make” command every time… so instead enter outline mode “Escape” key. And then just type t h to make a heading, or t c to make a codeblock.
Longer term to make this user friendly I’ll probably add a formatting toolbar, but that’s just UI. In the end it will just be calling the same code as the current commands.
Just tried this – very good to see headers imported from FT files automatically styled as bold.
Copy as Markdown worked well - though for the moment it only seems to copy the top level of of the document.
The t h, t q etc lin- type commands I’ve had less luck with – in my installation they seem to be tripping an error (attempt to read length of undefined) at line 30 of /birch-markdown-master/lib/birch-markdown.coffee
PS I notice that the markdown stylesheet is using the type names orderedlist and unorderedlist
Is that a deliberate move away from the set of (slightly shorter) node type names used in FT ?
(If so, I can update my FTSaveAsBML script to add an extra layer of node-type name rewriting )
For reference, the existing FT names are:
blockquote
body
codeblock
definition
empty
fencedcode
fencedcodebottomboundary
fencedcodetopboundary
footnotelinkdefinition
heading
headingunderline
horizontalrule
linkdefinition
linkdefinitiontitle
linkdefinitionurl
ordered
task
term
unordered
( I guess that the difference in line-type naming may also be which the Copy as Markdown in this package is not copying list elements exported from FT with the attributes data-type="unordered" or data-type="ordered", while it does work with data-type="heading" )
On my system, the t h, tq, etc commands do nothing. The shift-command-p make heading gives the error:
Atom Version: 0.184.0 System: Mac OS X 10.10.2 Thrown From: birch-markdown package, v0.0.0
Stack Trace
Uncaught TypeError: Cannot read property ‘length’ of undefined
At /Users/raguay/.atom/packages/birch-markdown/lib/birch-markdown.coffee:30
TypeError: Cannot read property 'length' of undefined
at Object.module.exports.BirchMarkdown.setItemType (/Users/raguay/.atom/packages/birch-markdown/lib/birch-markdown.coffee:30:24)
at birch-outline-editor.birchSubscriptions.add.atom.commands.add.birch-markdown:make-heading (/Users/raguay/.atom/packages/birch-markdown/lib/birch-markdown.coffee:12:42)
at CommandRegistry.module.exports.CommandRegistry.handleCommandEvent (/Applications/Atom.app/Contents/Resources/app/src/command-registry.js:243:29)
at /Applications/Atom.app/Contents/Resources/app/src/command-registry.js:3:61
at CommandPaletteView.module.exports.CommandPaletteView.confirmed (/Applications/Atom.app/Contents/Resources/app/node_modules/command-palette/lib/command-palette-view.js:120:32)
at CommandPaletteView.module.exports.SelectListView.confirmSelection (/Applications/Atom.app/Contents/Resources/app/node_modules/atom-space-pen-views/lib/select-list-view.js:338:21)
at space-pen-div.atom.commands.add.core:confirm (/Applications/Atom.app/Contents/Resources/app/node_modules/atom-space-pen-views/lib/select-list-view.js:109:19)
at CommandRegistry.module.exports.CommandRegistry.handleCommandEvent (/Applications/Atom.app/Contents/Resources/app/src/command-registry.js:243:29)
at /Applications/Atom.app/Contents/Resources/app/src/command-registry.js:3:61
at KeymapManager.module.exports.KeymapManager.dispatchCommandEvent (/Applications/Atom.app/Contents/Resources/app/node_modules/atom-keymap/lib/keymap-manager.js:558:16)
at KeymapManager.module.exports.KeymapManager.handleKeyboardEvent (/Applications/Atom.app/Contents/Resources/app/node_modules/atom-keymap/lib/keymap-manager.js:396:22)
at HTMLDocument.module.exports.WindowEventHandler.onKeydown (/Applications/Atom.app/Contents/Resources/app/src/window-event-handler.js:182:20)
Thanks guys, must be a bug in there… I’ll check it out in the morning.
Edit Ok, I see the problem. I made a change to Birch to support this, so it doesn’t work in the new version. So to fix you’ll need to wait for me to post a new version of Birch… I’ll do that tomorrow.
Good question… and no. This package was mostly just started as quick hack so that I could write users guide in Birch and publish in Markdown/HTML. I’ll swtich to using FoldingText style names in next version.
In playing with this, I’m wondering whether there may be some automated way to make this happen, provided the user follows (or sets) some kind of conventions. I’m thinking it might be tedious to assign properties in this way, especially to a big text.
Just thinking out loud, but I can imagine a setting (similar to what’s provided in iThoughts on iOS), where headers are added to everything at level x and higher (e.g, level four and up get #, ##, ###, ####) and everything else is paragraph.
As I’m writing this I’m not sure whether it would actually be easier to automate anything else: ordered and unordered lists could simply carry over if users append numbers or dashes prior to the line.
At any rate, my initial response prior to working with it for awhile is that the “outline editing mode” is really awesome for moving and arranging elements, but would be tedious to enter this mode back and forth just to create headers (which I do a lot to organize and which would map the indentation level here 1 to 1). Maybe a keyboard shortcut that could be invoked from “editing mode” would be fine.
I’m mostly just thinking out loud here, so I’m hoping just to start conversation rather than judge this or that approach.
List type continuation by default sounds good for a Markdown editing mode.
Top N levels as heading too – that would suit me very well.
I’m personally finding that the esc t q and esc t c etc. 3 tap sequences are quite brief and unintrusive, especially in combination with block select – consistent and mnemonic, perhaps easier to recall than the FT command keys –
but I can, of course, see the potential appeal of some shortcuts for use in edit mode ( if that looks like an option in the birch-atom model ).
Yeah, I agree that in general the UI can be improved in a number of ways.
Right now my goal is mostly to work on the underlying data model and set of core commands for manipulating that model. Once that’s more in place then I will look more at the UI (making commands easier to perform).
When I think about the potential for the UI I think of how it works now in FoldingText. For example in FoldingText you want to turn the current paragraph into a list. The sequence of commands to perform this is simple… start it with dash-space. But if you look at the sequence of keystrokes it’s quite long:
↓Command-Up↓ ↑↑ (to move to start of paragraph)
- Key↓↑
- Key↓↑`
And after this sequence you’ve lost your original selection, so theres then more keystrokes if you want to get back to where you were.
In Birch this can be much faster, because all it takes is issuing a single command. So if you want you can set a keybinding to do it all at once. For example, if you want to make a lists with Command-L in any mode you could do:
And in both cases your current selection is preserved so you don’t need to take extra time getting back to where you originally were. So that’s just all to say that the mental model (for basic formatting anyway) was simple in FoldingText, but actually pretty keyboard intensive to actually update. The Birch UI should be at least as fast and fluid, if not faster.
For more discoverable UI improvements I think:
A formatting bar, maybe popup like Medium.com, or maybe just at top of window.
Automatically set type for inserted items based on context (ie continue lists)
So eventually I think the UI will be pretty good, though right now there’s still quite a bit of work just working on core data model.
You’re right about this, of course, but because of the plain text aspect of FT, I always used Terpstra’s Markdown Services to accomplish these things without many keystrokes. Your walkthrough of the process with Birch shows that it can be just as simple, so that’s useful information. Thanks for detailing all this out–I know you’re working on more foundational stuff now and that the UX stuff will come later.