cabinSource code for personal website |
| git clone git://git.dimitrijedobrota.com/cabin.git |
| Log | Files | Refs | README | LICENSE |
Stamd.md (4801B)
0 @title: Introducing stamd
1 @date: 2021-08-18
2 @language: en
3 @categories: linux, c, personal projects,
5 # Introducing stamd
7 Stamd or static markdown is, as the name suggests, a static markdown page
8 generator, written in C, that I'm developing for use in this blog.
10 As I write more articles the program will get streamlined and I you will be
11 informed of any big changes down the road.
14 ## About
16 Motivated by [stagit](https://git.codemadness.org/stagit/), I've decided to take on this challenge
17 primarily because document parsing always fascinated me as well as to have a
18 complete control over to looks of articles the program produces.
20 I chose markdown as it's really simple and similar to HTML. I'm using it to
21 take personal notes in vim using vimwiki, which I am going to explain
22 in another article, so apart from already being familiar with it, I have some
23 snippets of content prepared and ready to share.
26 ## Challenges
28 ### List Items
30 The biggest challenge was parsing nested list items.<br>
32 - A standard list item is detonated with:
33 + `-`
34 + `*`
35 + `+`
36 - There is unlimited number of nesting that can take place
37 - Nesting No. 1
38 - Nesting No. 2
39 - Nesting No. 3
40 - Nesting No. 4
41 - After every nesting it is possible to return to any previous one
42 1. Ordered lists can be present on the same level
43 2. Like
44 3. this
45 1. Or they can be nested
46 2. With other ordered,
47 - Or Unordered variants
48 * While using the different detonator on the same level
49 + Must lead to new list being created
51 After a lot of thinking I've figured that in order to keep track of the nesting
52 level at any time, be able to return to the previous and create a new one, as
53 well as terminate all of the nesting at once on encountering a blank line, my
54 best bet is to use a stack to keep track of `<ol>`, `<ul>` and `<li>`, as well
55 as recursive function that calls itself for every new nesting level.
57 With this approach all of the heavy lifting is done by the recursion, which is
58 deepened by a bigger indent and returned by encountering a smaller one.
60 With a usage of global variables I am able to save the last recursion state
61 post return, and allow the lower level to continue like nothing has happened at
62 all.
64 Similar approach is taken to deal with nested `blockquotes` but with a different nesting detection and without a need to worry about the detonator
67 ### Inline blocks
69 There are quite a few options when it comes to text and inline block:
71 - ~~Strikethrough~~, detonated by `~~text~~`
72 - **This is bold text**, detonated by `**text**`
73 - *This is italic text*, detonated by `*text*`
74 - __This is bold text__, detonated by `__text__`
75 - _This is italic text_, detonated by `_text_`
76 - [This is a link](https://dimitrijedobrota.com/), detonated by `[Text](Link)`
78 This is, again, solved by a simple recursion that takes the pointer to the start and the end of the text, and parses that section.
80 If the detonator is reached, it checks if its closed properly, in which case
81 recursive call is made to parse only the text between the opening and closing
82 tags, after which the parsing resumes normally from after the closing tags.
86 ## Usage
88 The source code can be obtained using with:
90 $ git clone git://git.dimitrijedobrota.com/stamd.git
92 After that we need to use `make` to install it:
94 ```
95 $ cd ./stamd
96 $ make
97 $ sudo make install
98 ```
100 This will install `stamd` and `stamd-index` to be used anywhere in the system.<br>
101 If we run the commands now we will get a hint about their usage:
103 ```
104 $ stamd
105 stamd [-o outdir] articledir
107 $ stamd-index
108 stamd-index articledir articledir ...
109 ```
111 `stamd` requires that the article directory is provided. It looks for
112 `article.md` and `config.txt` inside the article directory in order to create
113 the output HTML file.
115 Providing output directory is optional with `-o outdir`
116 and it instructs `stamd` to place the HTML file in specified directory. If the
117 directory is not provided output will be placed in article directory.
119 ***
121 `stamd-index` takes in arbitrary number of article directories and writes, to
122 the standard output, the list of all the articles provided to be used as index
123 HTML file.
125 ***
127 You will also receive `create_articles.sh` script which I use to bulk create all of the articles and sort them by date.
129 If you want to use it for yourself, you will need to edit `blogdir` and `sitedir` to match your setup, and after that you can simple run:
131 $ ./create_articles.sh
133 ***
135 Config file, as of now accepts Title, Date and Language option. Every option should start in a new line and general format is:
137 Option: value
139 I am looking for a way to get rid of the config file in the future, so that all
140 of the necessary data can be extracted from the markdown file itself