In this tutorial, I will show you some useful techniques to take notes on a Jekyll website create with Github Pages and NoteTheme theme.
- 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.
- 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)?
- Easy to text. Support keyboard shortcuts, unicode, different language input (for example, Vietnamese input methods)
- 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.
- Mobility. We can check at any time, on any devices (computer, mobile, tablet,…)
- Clean & Neat. We can understand immediately what we have written.
- Math & Syntax highlighting code. They are important to me.
- Multi-platforms. We work not only on one type of device, it’s sure.
- 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.
- 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).
- 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.
- Supporting key-binding/keyboard shortcut (bold/italic texts, insert links, …)
- Supporting table of contents (toc) generated based on headings
- Supporting search and replace
- Supporting generating markdown syntax (differences for headings, code blocks, bold or italics texts,…)
- Supporting auto-completion
- Supporting syntax highlights for code
- 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
---, 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
In previous version of this post, I recommended using Marker on Linux. However, it supports weakly “search and replace” function. It meets also some “flash screen” error while typing and it doesn’t support table of content on the sidebar.
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
This corresponding to
http://localhost:4000. If you want to create 2 local websites, you can run the following line which is corresponding to
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.
- On the left: you choose
- On the right: you choose
- 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
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-folderbefore using FFS. If you don’t, there will be many conflicts with git which are not so easy to fix.
Working on different machines
If you work on many computers or many operate systems. You want that the change on
computer-1 will automatically update to
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.