In this tutorial, I will show you some useful techniques to take notes on a Jekyll website create with Github Pages and NoteTheme theme.

TL;DR

  • Using Github Pages for hosting website.
  • Using NoteTheme for a note-taking website’s template (I designed it).
  • Using MarkdownPad for a markdown editor on Windows, Marker on Linux.
  • Using FreeFileSync for transferring files between local repository and cloned repository from the remote.
  • Using git (terminal) for updating notes to the remote.
  • Working with many computers? Using Dropbox to store the local repo.

Prerequisites

  • A little bit knowledge about git.
  • Writing a markdown document.

Goals

  • Find a best easy way to write a note on a local machine and then publish it.
  • There are differences between what is on local and what is public so that you can check all things before pushing it to the remote.
  • Find some best tools for this purpose (and also know about other alternative tools)

This post supposes that you are going to choose a website for note taking but first, we make clear the reason why I recommend using a website instead of a note-taking app like Evernote.

What do we need about a note-taking service (app, website, tool)?

  1. Easy to text. Support keyboard shortcuts, unicode, different language input (for example, Vietnamese input methods)
  2. Search & Replace. We can come back any place we want to modify, supplement or delete something. Sometimes, we want to replace a lot of the same words with other ones. This function is really necessary.
  3. Mobility. We can check at any time, on any devices (computer, mobile, tablet,…)
  4. Clean & Neat. We can understand immediately what we have written.
  5. Math & Syntax highlighting code. They are important to me.
  6. Multi-platforms. We work not only on one type of device, it’s sure.
  7. Free. It’s optional, we prefer services at lower cost.

Evernote lacks function 5. Other note-taking apps almost lack functions 3 and 5 except some below apps.

  1. Quiver: It’s great (I used it before and I love it for the first time). It supports all of the above things except the function 6 because it’s only available on MacOS and iOS. It’s not also free, you must pay 10$ to get the full version (but it’s cheap).
  2. Bootsnote: It surprised me with its current features because when I met it for a year ago, it likes other ones which lack many features. Honestly, with Bootsnote now, you have all above needs except that, you can only sync your notes via Dropbox (but not so easy to do that).

How about others? Google Keep (it’s a to-do list app), SimpleNote (it’s not good for math and coding), OneNote (It’s so complicated for quickly noting, its block styling mechanism seems to be annoying and it’s not good for math and coding notes), Zoho Notebook (it likes Google Keep), Bear (it’s not free and only for Apple’s services), Squid (it’s for handwriting-supported devices).

Creating a note-taking website

Read this article to create a free website with Github Pages and NoteTheme theme. Because I created this theme (I actually modified from Matjek), it has most of the features we need for a note-taking service listed above.

  • Clean & Simple & Beautiful (see demo)
  • Full supports and frequently update
  • Support a lot of useful components for taking notes (see full list)
  • Display Table of Contents automatically on a fixed sidebar (and on the post content)
  • Integrate disqus comment system.
  • Integrate Mathjax which supports typing math equations.
  • Integrate DataCamp Light which supports embedding side-by-side Python/R code environment (see demo for this)
  • Support search on site quickly (demo)
  • Support tags and categories for posts.
  • Mobile friendly
  • Search engine friendly
  • Invisible option: make your site invisible to search engines

Because they go together, free and easy to setup. You can also couple Jekyll with Gitlab Pages but there are some disadvantages of Gitlab in comparison with Github Pages (complicated to setup, long time generating, non-flexible urls,…). However, Gitlab has advantages in giving free private repositories and supporting third party jekyll plugins. It depends on you to choose but I recommend Github Pages.

Texting with Markdown

When working with Jekyll and Github Pages, you must choose a “good” markdown editor: easy to edit and organize the document.

  1. Supporting key-binding/keyboard shortcut (bold/italic texts, insert links, …)
  2. Supporting table of contents (toc) generated based on headings
  3. Supporting search and replace
  4. Supporting generating markdown syntax (differences for headings, code blocks, bold or italics texts,…)
  5. Supporting auto-completion
  6. Supporting syntax highlights for code
  7. Supporting tab codes, math block, quotes, …)

For my personal experience, a good markdown at least has 3 features “1 to 4”.

Sadly, there is no markdown editor supporting all the above features (I tried them all).

  • You may find on the first results on Google that Typora is the best one for typing Markdown. However, it’s advantage is also it’s disadvantage when our note takes large and complicated contents (especially for codes).
  • Abricotine is also a good choice but less “WYSIWYG” than Typora. However, when our block of codes contains symbol # or ---, it automatically uses markdown engine to convert to corresponding html syntax. That makes our document look ugly and it’s not good for note taking.

What we need is a tool at least has the ability to search and replace so that we can modify many “wrong words” at the same time. We also need to distinguish headings, code blocks, links, images for easily typing texts. The most necessary feature is the supporting of keyboard shortcut, for example, we just use Ctrl + B to bold a text instead of typing 4 times symbol * or use Ctrl + K to insert quickly a link instead of typing a full phrase [text](link), …

For that need, I recommend using MarkdownPad (Windows) and Visual Studio Code with extensions Markdown All in One and Markdown Shortcuts (Linux). I have not tested any app on MacOS.

Create a local website which is the same to remote

We don’t want our drafts or under-modifying templates are exposed to the public while they are not ready. We want to have a very the same website with the real one on our local machine so that we can make every test on it before publishing.

You can read this article for a full instruction of creating a local Jekyll website. When you want to run it, you just run

$ bundle exec jekyll serve

This corresponding to http://localhost:4000. If you want to create 2 local websites, you can run the following line which is corresponding to http://localhost:1234.

$ bundle exec jekyll serve --port 1234

Sync between local and remote

When working with local website and remote website at the same time, you will have two separated folders located on your computer: one for local (local-folder), one for remote (remote-folder). You make some changes on local-folder but what you use to push to remote is the content in remote-folder. You cannot track by yourself the changes and do the copy-paste work. FreeFileSync will help you to do that. It determines automatically the differences between two folders.

Hình: FreeFileSync UI (source: FreeFileSync) FreeFileSync UI (source: FreeFileSync)
  • On the left: you choose local-folder.
  • On the right: you choose remote-folder.
  • You choose option Mirror in the Synchronize button. This choice will track all changes on local-folder (by pressing button Compare) and then overwrite them to remote-folder (by pressing button Synchronize). You must be careful on this step because all contents on the right will be lost and be replaced by the left’s ones.
  • If there are some folders or files you don’t want FFS to compare between two folders, you can choose them and then make a right click to choose Exclude via …. All the exclusions will be saved and FFS will not compare them on the next time.
  • Don’t forget the small section on the bottom left window, you can exclude a folder in this section.
  • Use the icon Save on the top left window to save all your settings for the pair local-folder-remote-folder. Next time you want to compare them, just double-click on the saved title.
  • Don't forget to pull all changes from the remote to remote-folder before using FFS. If you don’t, there will be many conflicts with git which are not so easy to fix.

You can use either Github Desktop (Windows, MacOS) or GitKraken (all platforms) to clone, pull, push the changes between remote-folder and remote (Github’s server).

Working on different machines

If you work on many computers or many operate systems. You want that the change on local-folder on computer-1 will automatically update to local-folder on computer-2. It’s easy with a sync service like Dropbox, Microsoft OneDrive or Google Drive. I choose Dropbox because we don’t need to download again the content from remote to local whenever we reinstall the computer and there is still an old dropbox folder on it.