A quick exploration of classeur.io

Posted on by Shawn

My quest to find a good open notebook approach for my tech-hesitant students continues. Today, we’re playing with Classeur.io

  • classeur.io : another note taking app; lives in browser or on desktop or as app within chrome. Stores your notes in a database in browser storage
  • documents also copied onto classeur servers; can get a URL to allow sharing/viewing (collaborative writing via the shared URL is a premium service)
  • uses visual metaphor of folders for different projects; write in markdown
  • exports to html, txt, or pdf via integral pandoc integration, but free tier only allows small files (5kb!)
  • has REST api; in free tier this is read-only
  • can push documents into Github, blogger etc. One integration is allowed in free tier

There are so many markdown editors out there; why would you use another one?

  • my open notebook arguments (see workbook.craftingdigitalhistory.ca, Caleb McDaniel’s Open Notebook History and Chad Black‘s ‘The Individual Research Archive: Hacking the Papers of You’)
  • Visual metaphor of notebooks is a low-friction signal for students who are techno-hesitant
  • Visual metaphor of notebooks helps nudge organization
  • folders and formatting-showing-as-you-go
  • accessible across any device
  • push-to-github is done at the level of an individual note. So it allows you to keep what needs private, private; what can share, be shared; can push into something like jekyll-now or other static gh-pages type thing
  • classeur-downloader, built on top of the API, will grab all your files/folders out of classeur – the free tier allows access this way. Files/folders can be grabbed as markdown or as json (json has more metadata etc)

A word on attaching a file to github

  • I spent a couple of hours fighting with this. The problem was that I wasn’t scrolling down in the pop up box! I swear, I looked at it for hours and didn’t realize that the box had more in it that what was displayed (perhaps this is a UX fail? I didn’t notice the signal that one could scroll downwards).

So to connect:

1 – in the web version of classeur, login with whatever credentials you are using (in my case, my google + account, what the hell.)

2 – click on the cogwheel to bring up the settings menu

3- in settings, click on ‘link blog’.

4- in the pop-up, choose your plaform. Let’s select Github. The box changes slightly. Give it a ‘friendly name’. Put in the URL to your repo. Tick off the ‘private repo access’. I don’t have a private repo, but this seemed to be necessary to get Classeur to talk to Github to enable read/write. You should get redirected to github at this point; login, authenticate, whatever.

Now go create a new document. (Click out of the settings page by hitting the big ‘x’). Write away to your heart’s content. To push to github

1- Click on ‘menu’ on the right hand side of the notepage.

2- Click ‘post to blog’

3- In the dialogue box, click your ‘blog’, ie, github.

4- Another dialogue box. In ‘file path’, you write the actual path relative to your repository AND a file name. So let’s say I have Classeur connected to https://github.com/digh5000/exposednotebook. I would write this for ‘file path’:

_posts/2016-01-20-a-notecard.md.

In which case, this file from Classeur shortly will be found at https://github.com/digh5000/exposednotebook/_posts/2016-01-20-a-notecard.md .

That is, the last bit is the actual filename of my note for the purposes of fitting into the Jekyll conventions (if you’re not using Jekyll to serve up a blog via Github, don’t worry, just name it whatever you want. Best not to have any spaces, though). In my Classeur, it might carry a different descriptive title (which may or may not be a good idea). Now, SCROLL DOWN. You need to also say which branch you want. In this example, I need my gh-pages branch. (This was the trouble I was having the other night, by the way. A simple thing to miss, but frustrating as all hell when you do). Then hit ‘post’. A little box will load up in the bottom right of your screen telling you you’re posting; if all is successful, it will say so. If there is not ‘blog posted’ note, something went wrong.

5. Going forward, a little cloud with a right arrow icon will be a tab on your document. Anytime you make changes, you can just hit that icon and it will push it to github.

Getting your data out

Use Classeur-downloader. This is written with Node; I will leave the details of installing node up to your Google-fu. Then, install as per the documentation

Then, from your command line or terminal:


# Save markdown content of all files in two folders to a directory:
cldownload --user-id 'my id' --api-key 'my key' save --folders 'folder id 1' 'folder id 2' --save-path /path/to/dir --markdown

# Save the full Classeur API metadata and data for a file into a single JSON document:
cldownload --user-id 'my id' --api-key 'my key' save --file 'file id' --save-path /path/to/a/file.json

# Print out a tree of all files in a given folder:
cldownload --user-id 'my id' --api-key 'my key' list --folder 'folder id'

# Global help:
cldownload --help

# Subcommand-specific help:
cldownload list --help
cldownload save --help

The key thing is to find your user-id and api-key. You get it from clicking on the cog-wheel icon, then User. Your user-id will be visible there; copy and paste it somewhere handy on your machine. Your API-key is right below it, but hidden. Hit the refresh button beside it, and a new one will be generated and will be visible (for a limited time!). Copy that and keep it handy on your machine.

Then, you need to figure out what the IDs are for your folders or files. Easiest way I’ve found of doing this is to click on the Menu when you’re working with a file, selecting share, and then copying the URL: https://app.classeur.io/#!/files/string-of-letters-and-digits . The bit after /files/ is what you want. For folders, you share by clicking on the 3-dots icon beside the folder name, selecting sharing, and grabbing the URL again. You don’t have to actually share; it’s just a quick way of grabbing the unique IDs for your material.

I now have a little command line properly formatted that I can run in the terminal, in the folder I want to copy my private stuff to; public stuff can be pushed to github or shared within Classeur itself.

I will note that if you pay for the $5 monthly version, a lot of this becomes extremely easier, and includes integral pandoc translation into other formats etc. For some users, this might just be the sweet spot.

Verdict?

I like Classeur; I need to think carefully about how to make it integrate with the workflow I’m trying to inculcate in my students. On balance, this works.

A parting thought – Classeur is by the same folks who do Stackedit.io. One might reasonably ask, ‘why don’t you just get your students to use Stackedit then?’. I think part of the answer is in the visual cues that Classeur gives regarding organization. Also, in many regards, Classeur has the right amount of slimmed-down features that I like; there is less cognitive load whilst using it (when you have markdown on the left and the rendering on the right, it can be confusing for the newcomer).

The proof is in the pudding though. I should really use it for an actual project from start to finish. Then we’ll see how it goes. I have been (slowly) transcribing a traveler’s diary to Egypt in 1874; maybe I’ll use Classeur for my transcribing work, and use it to push to Alex Gill’s ‘Ed. A Jekyll Theme for Minimal Editions‘. Stay tuned!