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