Markdown, Notable, and Hugo
Markdown, Notable, and Hugo
I wanted to record in my notebook what I wanted to do. I wanted to track the process of learning and trying. The results and conclusions are important, but the process of obtaining them is just as important. Once that happens, I want to be able to create notes and add and edit them later. I wanted to link to the note, add an image, and add a diagram if necessary. When the note was finished, I thought it would be great to have it automatically registered in the same or similar format that I wrote in the note, along with the tags I wanted for my blog. I have more ideas, but for now, I implemented this first.
What if you could just produce content in pure text?
There are many applications for managing your notes. Looking back at the applications and services I've been through, everyone seems to have their own advantages and disadvantages. However, it was annoying that many of those applications or services used their own formats, or formats that were not easy to reuse later.
To answer my question about myself, I did a Google ring and learned the Markdown format. When I see a coworker writing a development document based on a certain format, copying and pasting it, converting it to a google document, and registering it, I'm overlooking why it is so uncomfortable. Later, when I learned about Markdown, it was Markdown.
Can I manage my todos?
Then came GFM (Github Flavored Markdown). Here's a modified version with to-do lists, tables, canceled text, and automatic links.
To do list
-[] to do 1
-[] to do 2
-[] to do 2-1
-[X] to do 2-2
-[X] to do 3
to do 1
to do 2
to do 2-1
to do 2-2
to do 3
table
| foo | bar |
|---|---|
| baz | bim |
foo bar
baz bim
Canceled text
Abe ~~ Fool ~~ Fighting!
Abe stupid fighting!
Auto link
https://google.com
https://google.com
Is a diagram possible?
Knowing that GFM supports tables, I wanted to see if they could be used in development documentation. By the way, what was sometimes needed for development documentation was diagrams. In the past, Google documents have been created by attaching google diagrams after attaching them. By the way, when I attached the diagram to an e-mail sent to someone who doesn't have access to Google Drive in-house, I thought that I should convert it to an image and attach it.
The Google Ring, which tells everything, led to Mermaid. Within the Markdown file, I could simply display the flow chart, sequence diagram, and gantt chart as text.
For reference, the following charts are all expressed as svg in the linked original page.
Flow chart
graph LR
A [Hard edge]-> | Link text | B (Round edge)
B-> C {Decision}
C-> | One | D [Result one]
C-> | Two | E [Result two]
Sequence diagram
sequenceDiagram
Alice->> John: Hello John, how are you?
John->> Alice: Great!
Gantt chart
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task: done, des1, 2014-01-06,2014-01-08
Active task: active, des2, 2014-01-09, 3d
Future task: des3, after des2, 5d
Future task2: des4, after des3, 5d
section Critical tasks
Completed task in the critical line: crit, done, 2014-01-06,24h
Implement parser and jison: crit, done, after des1, 2d
Create tests for parser: crit, active, 3d
Future task in critical line: crit, 5d
Create tests for renderer: 2d
Add to mermaid: 1d
Dedicated Format vs Plain Text File
Most applications / services you've experienced use proprietary formats. If necessary, you can export it, change it to another format, and import it again. However, the use of proprietary formats is a barrier whenever you switch to other applications / services. So I wanted a plain text file to be available. If your notes are managed as a plain text file, if your files are managed by git or a cloud service that supports change history, you may be able to see the history of your changes. Note You could freely search for content without depending on the application or service.
Filename
Assuming it is managed as a plain text file, the next thing to think about is the file name. If this file name is randomly generated to distinguish files, such as uuid, the file name itself will have a value of zero as information. In terms of applications and services, the file name and the title of the note can be managed separately, which may be advantageous in terms of implementation. However, if the note is managed as a plain text file, it is better that the file name is also defined as given by the user. When viewing a note file in File Manager, Filename = Note Title will be much more useful for searching and separating notes.
Classify notes
Now suppose the notes are managed in plain text with meaningful file names. Even if the note title is a file name, it is not easy to sort the note by the title alone. You could of course use a prefix, but I think you should be able to categorize your notes, apart from the title. However, if the classification is not a separate trick or db, but the note file itself is saved, even when the note is opened in a separate application, the classification information can be referred to as it is. Although note classification may be in several stages, one stage may be sufficient for practical use.
Which application or service would you like?
Taking notes is a very common practice, and there are always many applications and services in the world. Naturally, I have not used all of them. However, it's clear that Notable is one of the answers we've seen so far that satisfies all of the requirements listed above.
Notable
Joplin was a very, very strong candidate, including cli, mobile app support, and web clipping extension support, but eventually sought again to find and find Notable because of the uuid filenames and classification information stored in certain files.
Notable
Notable stars
The number of stars on Github is nearly 12,000. Perhaps one of the main reasons is that it is managed as a plain text file rather than using a proprietary format.
File management
The file management structure is as simple as: The notes and attachments directories are used under the Data directory. As expected, * .md is kept in the notes directory and all attached files are in attachments. Therefore, it is not possible to create a note with the same title, and upload the same attachment. If you don't like these restrictions, you should never use Notable, but if you have to choose the benefits of accepting them, Notable is a natural choice. Even though features that Notable doesn't provide (mobile apps, web clipping, etc.).
/ path / to / your / data_directory
├─┬ attachments
│ ├── foo.ext
│ ├── bar.ext
│ └──…
└─┬ notes
├── foo.md
├── bar.md
└──…
Meta data
attachments: [build.sh, duplicated_titles.jpg, notable_stars.jpg, notable_tags.jpg, notable.jpg, notetaking.jpg, relref.jpg]
pinned: true
tags: [Tag 1 / Tag 2, Tech]
title: "Markdown, Notable, and Hugo"
date: '2019-04-29T09: 14: 11.205Z'
lastmod: '2019-08-04T02: 16: 46.135Z'
This is the meta data for this note. Below this area is just plain text. As you can see it contains a list of attached files, tags, filenames, and creation / modification date and time.
Filename
Synchronizes with the first header (#) in the note. In other words, if you modify the first header, the file name is also changed. By the way,