Welcome to geekbook documentation!¶
G33KB00K - 🤓 eXtreme eXtendable note taking system for nerds/geeks (including scientists!) (= beautiful html generator of your markdown-based notes) docs: http://geekbook.rtfd.io
Marcin Magnus (mmagnus) & Pietro Boccaletto (akaped)
The code of the project can be found at GitHub (https://github.com/mmagnus/geekbook).
A neat way how to combine Emacs/Atom/Sublime editor + Markdown Syntax + Git + Html engine (bootstrap/python) to get the best notes-talking experience ever. Highly customizable with plugins written in Python. What’s the most important, under the hood it’s just a set of Markdown files.. you can do with them whatever you want, e.g. you can Pandoc (http://pandoc.org/epub.html) them to epub (that’s origin of “book” part of the name).
The preview of the default template:
Features:
- Index html based
- Sync them with Dropbox/iCloud/github
- Read from console, grep them
- Edit with almost any text editor, I’m using Emacs!
- Keep images separately, edit them in any external tool or edit them in batch
- Customize html templates
- You can sync notes in your system with notes kept at virtual machines (mounted via sshfs) or drives
- Super light!
- Pandoc markdown files to anything you want!
- Use 3rd party editors, if you wish, on your computer or on your phone.
I recommend to use Emacs (or VIM or other super-powerfull editor) to:
- run git on your notes in your editor,
- grep them in the editor,
- make bookmarks to parts of your notes,
- copy-paste from your notes to your programs you’re writing,
- use Google Translate (https://github.com/atykhonov/google-translate)
- ispell,
- outline mode,
- focus mode.
The main documentation for the site is organized into sections:
Information about development is also available:
Installation¶
Get it the project:
git clone https://github.com/mmagnus/geekbook.git
or download https://github.com/mmagnus/geekbook/archive/master.zip and unzip.
To install, type:
pip3 install --user -r docs/requirements_user.txt
and go to Get Started! :-)
Get Started¶
Run geekbookapp.py:
[mm] geekbook git:(master) ./geekbookapp.py
2017-01-10 09:47:46: (network.c.410) can't bind to port: 1234 Address already in use
Could not execute http daemon lighttpd -f.
The file /private/tmp/geekbook/engine/data/html/index.html does not exist.
________ __ __________ __
/ _____/ ____ ____ | | _\______ \ ____ ____ | | __
/ \ ____/ __ \_/ __ \| |/ /| | _// _ \ / _ \| |/ /
\ \_\ \ ___/\ ___/| < | | ( <_> | <_> ) <
\______ /\___ >\___ >__|_ \|______ /\____/ \____/|__|_ \
\/ \/ \/ \/ \/ \/
2017-01-10 09:47:46,585 - geekbookapp.py - G33kB00k is Running... [ok]
2017-01-10 09:47:46,585 - geekbookapp.py - root path: /private/tmp
2017-01-10 09:47:46,585 - geekbookapp.py - html path: <file:///private/tmp/geekbook/engine/data/html/index.html>
2017-01-10 09:47:46,585 - geekbookapp.py - imgs path: /private/tmp/geekbook/notes/
2017-01-10 09:47:46,586 - page.py - IOError: test.md
2017-01-10 09:47:46,587 - page.py - compiling --> test.md
2017-01-10 09:47:46,589 - postprocessing.py - youtube video detected: ICDGkVbSWUo
the web browser of choice should open with the index page. You should see the test note.
You’re ready to edit your notes.
Edit your notes in `<path to your geekbook>/notes/<note>.md`.
Keep the geekbookapp.py program running in the background. Whenever you edit an old note or add a new one geekbookapp.py will compile it not into a web page. Refresh the web page and you will see your note in the index or the note will be compiled on the note page.
Enjoy!
In | Write¶
Editors (with Markdown support)¶
It’s important to use a good editor with support of Markdown.
I’m (mmagnus) using EMACS (https://en.wikipedia.org/wiki/Emacs), sometimes I use MacDown (http://macdown.uranusjr.com/) or Atom (https://atom.io/).
Emacs¶
Fig test.md in Emacs. I love EMACS for this Outline Mode - you can see immediately the structure of your note, it helps to navigate and understand (= keep it clean) your note.
Fig Emacs can “split” a note for you, so you can work in two (and more) places of your note at the same time!
Markdown (Github-Flavored Markdown)¶
Write your notes using Github-Flavored Markdown! Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.
GitHub Flavored Markdown is a version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with your notes.
- the basics https://help.github.com/articles/basic-writing-and-formatting-syntax/
- https://guides.github.com/features/mastering-markdown/
- https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
Syntax highlighting¶
Type:
``` js
var foo = function (bar) {
return bar++;
};
console.log(foo(5));
```
Read more https://help.github.com/articles/creating-and-highlighting-code-blocks/
Geekbook Only¶
This a set of extensions developed by the Geekbook community.
Find Files¶
Type [ff:<name_of_the_file>] to trigger locate (on Linux) or glocate (on macOS, install brew install findutils) to find a full path to your file and insert it in the given place in a generated html.
Warning
You have to keep you locate database up to date, use sudo updatedb (on Linux) or sudo gupdatedb regularly.
Example:
to get this:
Warning
For many links in one note, this might be slow to re-generate (geekbook has to locate all files). We might want to develop some cache system to speed this up at some point. Yeah, there is a cache system now implemented. All paths are save to find_file.json, and if your file has been seen before, the path to that file will be recover from the db. @todo: Now we need a script that will update this database from time to time.
Insert File¶
Wherever you want to insert an external file, you can use:
[if:<path>]
e.g.
[if:/Users/magnus/work-src/fenzymes/examples/readme.txt]
and the file will be included in your Markdown content. The file can be written in Markdown, if so, it will be processed as your regular Markdown content.
Table of Content¶
Type [tableofcontent] or {{TOC}} to get the table of content of a given note.
Date¶
Type [date] to get the current date 2017-01-13 with:
with time.strftime("%Y-%m-%d", time.localtime(os.path.getctime(<md file>)))
Insert Image¶
Type \ii (and only this in a line) to ask geekbook to copy the last image from the folder when you keep you screenshots to
the folder with your images:
Before in your markdown file:
\ii
save the file, reload the file to get:
To turn on this plugin in your ~/.geekbook.py set the path, e.g.
SCREENSHOT_INBOX = '/Users/magnus/Desktop/'
In similar way you can define the second location that you want to use for Inserting Images, such as:
SCREENSHOT_INBOX = '/Users/magnus/Desktop/'
INSERT_IMAGE_TAG = '\ii' # 'ii'
SCREENSHOT_INBOX2 = '/Users/magnus/Dropbox/'
INSERT_IMAGE_TAG2 = '\id' # 'id'
Paste Image¶
Type \ip (and only this in a line) to ask Geekbook to paste an image from your clipboard. A new file will be created with the contact taken from our clipboard, for example:
Images: formatting¶
Warning
The syntax =100x) does not work at the moment. Please use ![#mini] (see below)
You can define width and height for your images as follows:
Read more in the function documentation:
If you want to position more images next to each other, you can use tables. They will be autoscaled for you!:
Fig. gab | gab+pk | gab+pk (2)
----|------------------|--------
 |  | 
 |  | 
which will give you:
Or just simply put pictures next to each other:
 
Insert Image from DropBox link¶
If you use a Mac and you like to store your images in Dropbox this is the function for you! I (akaped) use it to take screenshot with my mac, dropbox will automatically take the screenshot, copy it in a synced screenshot folder and return you a link ( in your clipboard !).
What do you need to do now ? Just paste the link in your text editor, save the file, and whatch it change !
ex. Dropbx link ` https://www.dropbox.com/s/1yu4r8aosqwky4r/Screenshot%202017-01-20%2023.49.26.png?dl=0 `
Paste - Save > geekbook returns pure wonderful markdown ``. This will be then processes in html to appear as smooth as possible in your geeky notes.
DANGER! : This function changes your markdown file! You need a good text editor like emacs or Atom to detect this change in your code and avoid a possible crash.
Abstract¶
Start a line with ```! ```(mind the space after !) to mark the fragment as an abstract.
You can collect all lines marked as an abstract, use tag [abstract]:
! ble ble ble
[abstract]
# task
! summary of task
it will give you:
Ble Ble ble
Summary of task.
The last sentence is collected along a note.
Youtube¶
Make you notes look more fun! You can insert a youtube video by typing `[yt:video id]`:
Where video_id corresponds to the 11 alphaumeric characters that you can see in the youtube url of your video.
Ex. dj kitty – url – https://www.youtube.com/watch?v=ICDGkVbSWUo its video_id = ICDGkVbSWUo
Type in geekbook `[yt:ICDGkVbSWUo]` to visualise one of our favourite Djs.
Task status¶
It’s fun to take notes and to take track of our projects ? Isn’t it ? Now you can type these useful tags in your notes to know what was done, what are you doing and what to do !
Type `@todo`, `@done`, `@progress` to get:
How do we use this ? We like to introduce this tag in our titles to follow our progresses.
`## 19.02.2017 - Go to buy the milk for Dj kitten @done`
Out | Read¶
Fig. The index in Safari.
Of course you can browser your notes in any browser. I used to use Firefox, then Chrome, and now Safari :-)
*Book¶
Geekbook is a book because it can actually make full books!
We’re testing this right now, stay tuned.
We’re using Pandoc to convert to pdf/epub/tex etc :-) Pandoc can produce output in the EPUB electronic book format. EPUB books can be viewed on iPads, Nooks, and other electronic book readers, including many smart phones. (They can also be converted to Kindle books using KindleGen.). This means that it’s now very easy to produce an electronic book! Read more <http://pandoc.org/epub.html>
See a plugin of Geekbook here <https://github.com/mmagnus/geekbook/tree/master/plugins/bookify>
Geekbookapp¶
Local configuration of your own Geekbook¶
To set up your own variables that can be used by Geekbook you can edit the sample in engine/ folder conf_local.py_sample. Copy conf_local.py_sample to conf_local.py and comment (or remove) variables that you don’t want to change from default. The default variables are define in conf.py).
For example, to define your own source of screenshots, make a config file like this:
engine$ cat config_local.py
SCREENSHOT_INBOX='/home/Thomas/Desktop/*png'
and restart geekbookapp.py.
Quick Reference¶
find a full path to your file and insert it in the given place in a generated html
[ff:<file>]
[ff:uniq-name.pse]
insert an external file
[if:<file>]
[if:/Users/magnus/work-src/fenzymes/examples/readme.txt]
insert an image (start a line without any extra characters before /,
which you can use also to block this function by putting a character before /
/<path to an image>
or
files:///<path to an image>
(mind that this function will change the original MD file (not only HTML output),
so your editor should be enabled to re-load a changed file from the disk
insert the table of content in here
[tableofcontent] or {{TOC}}
to get the current date 2017-01-13
[date] or {{date}}
define only width for a image:
only height:
and both:
you can put to images next to each other and sqeeze them to the left
<div style="width:300px">
</div>
#short - set for image (``max-height:400px``) to make it shorter
add description of a note in the Index page
[desc:info on TN]
insert a file and remove the first line and shift all headers by one to fit
the structure of the file where you import to
/[file:hacking-convert-pdf-to-images.md =del1 =shift1]
recompile master note with a give note when the note is changed
^[file:master-notes-for-this-one.md]
\ii - copy an image file from Desktop to Geekbook and insert a link in a Markdown file
\ip - copy a clipboard an image file and insert a link in a Markdown file
\id - copy an image file from Dropbox to Geekbook and insert a link in a Markdown file
[yt:<youtube video id] - this will insert the HTML code for YouTube video in the output html page
[yti:<youtube video id] - this will insert the HTML code for YouTube video in the markdown note !
Food for thoughts¶
Simple plain text writing¶
It’s easy to obsess more about your writing setup than your actual writing, but when inspiration strikes and you actually want to—you know—write something, nothing should stand between you and putting your thoughts on paper, digital or otherwise. Distraction-free writing environments are all the rage, but here’s the thing: You can set up a writing environment so free from distractions it’s the writing equivalent of a sensory deprivation tank, but if all that fiddling places any barrier between you and your goal—to actually write—it’s not worth it.
http://lifehacker.com/5684804/set-up-a-writing-system-that-stays-out-of-your-way
What Is Markdown, and Why Is It Better for My To-Do Lists and Notes?¶
Markdown uses a very simple formatting syntax to accomplish the same thing that HTML or Rich Text Formatting does. The difference is that it’s simpler than HTML and you don’t have to worry about opening and closing tags. It also doesn’t have all of the menus associated with most text editing programs. To format text, Markdown uses punctuation and characters you’re already familiar with.
http://lifehacker.com/5943320/what-is-markdown-and-why-is-it-better-for-my-to-do-lists-and-notes
Long notes vs short notes¶
It seems that if it make sense try to make long notes. One project should be a long note. You have everything in one place, and you can just scroll up or down and use the table of content sidebar to get where you want, it’s a really time saver! Not having to click and go to a different note, it’s really fun and help you focus on your work. That’s why Word doc files don’t work for me, it’s to hard to find yourself easily and for very big files, Word is just super slow!
However, if you have a note that is clearly self-containing, separate from everything else, use a new note. It will be faster to read or/and edit on mobile devices, easier to print.
Git/Github your notes¶
We develop a plugin to automatically git your notes. The script can be added to your crontab.
geekbook/plugins/ContentAutoCommit/git-auto-commit.sh
Magnus: I realized that I prefer to commit changes of my notes by myself. I usually improve some new information, fix some notes etc. So I developed the script but I’m not really using it right now.
Images (external)¶
It’s also very useful in some applications to have images seperate than your notes. You can have dynamics notes, where your images are in varous places and you provide in Markdown links to them. You can also grab any image to Gimp, edit it and just save. The image in the note will be updated then. You can edit images in batch.
Styles¶
Geekbook compared to Word is very easy to stylish however you want :-) It’s just HTML. You can do whatevery you want using CSS etc.
Version control of your notes¶
If you use git, you can keep all version of your notes, you can track the whole history, in the similar way how you can deal with your code.
Super-flexible¶
This system is super flexible. You can use whatever editor you like, you can edit your notes on your phone, one a cluster using Vi/Nano/etc. It’s text file so you will be able to open it alwasy in the future.
Cool alternatives¶
- Geeknote http://www.geeknote.me/ - Work with Evernote from command line
- KeepNote http://keepnote.org/manual/#philosophy
- Notes https://github.com/pimterry/notes
Miscellaneous¶
Geekbook on Mac¶
Spotlight¶
Before using Spotlight you tell Spotlight to stop indexing folder geekbook/engine/data/orig. Thus some technical copies used by Geekbook internally of your notes will not be index by Spotlight.
Read more: http://osxdaily.com/2011/12/30/exclude-drives-or-folders-from-spotlight-index-mac-os-x/
How to backup your notes?¶
Dropbox¶
You can keep your notes under Dropbox etc.
Git (GitHub)¶
If you want to backup your notes, we recommend to use git :-) and keep your notes as you keep you source code and commit changes and push it to your private (so no one can read it ) repository. For private repositories you can use GitHub but you have to pay.
You can how your notes always online!
Borg (to a remote machine or external drive)¶
You can use Borg. Borg (BorgBackup) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption.
Use something like this:
export BORG_PASSPHRASE='<you secret password>'
export BORG_REPO="malibu:~/notes" # where malibu is a remove machine
borg init malibu:~/notes
borg create -v --stats malibu:~/notes::{now} ~/geekbook/notes
# remove your old backups notes
borg prune --list -v $BORG_REPO --keep-daily=7 --keep-weekly=4 --keep-monthly=6
make a bash script and add it to your crontab:
@hourly ~/bin/notes-backup.sh
Borg is way more complex than this. Read please Borg.
mmagnus/rna-tools¶
You need to install rna-tools (http://rna-tools.readthedocs.io/en/latest/) first.
Draw VARNA-based image of RNA secondary structure¶
Type:
<pre>[ss:rna]
UUUCUGUAUAAUGCCGAUAAUAAGGUUCGGCAGUUUCUACCAAACAGCCGUAAACUGUUUGACUACAGUAA
((.(((((...((((((.........))))))........(((((((.......)))))))..))))).))
</pre>
Warning
Keep exactly the same syntax as in the example above and below.
The syntax:
<pre>
[ss:/name of your seq/]
/seq/
/ss/
</pre>
# ^ not <pre/> nor <pre>. Keep a new line after this syntax. So don't do:
</pre>
<pre>
but
</pre>
<pre>
# ^ this could be fixed at some point
Warning
This plugin will change your Markdown file, so make sure that your editor will detect this change and ask you to reload the file!
to get a VARNA-drawn image of secondary structure.
Development¶
Configuration¶
Geekbookapp¶
Page¶
Make Index¶
Make Table of Contents¶
geekbook - table of content
Get markdown output and make a table of content!
h1 How my lifebook should look? id_of_div How-my-lifebook-should-look?
changelog:
- 2012
- 0831 fix of the previous point
- 0829 make h1 clickable
Preprocessing¶
Postprocessing¶
Flask-based actions¶
Run the server:
[mm] geekbook git:(master) ✗ python engine/webserverflask.py
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
and open in your browser http://127.0.0.1:5000/edit/test.md (you can add this to your notes
<a href="http://127.0.0.1:5000/edit/test.md">edit</a>.
To add new function, build on this simple example:
@app.route('/edit/<note_title>')
def edit(note_title):
"""Open a note with your edit"""
os.system('open ../notes/' + note_title)
return 'edit note: %s' % note_title
DataTables¶
Html code to be inserted dataTables [1] for index can be found in engine/make_index.py.