updated docs

README.md

@@ -4,7 +4,7 @@
 A simple Odin program that is used to generate my site!
 
 Note: This is incredibly specific! If you want to use this for your own sites, I think it would be easier to write 
-your own! 😅
+your own!
 
 ## Usage
 
@@ -32,7 +32,7 @@ odin build .
 ### Todo
 * Indexing Articles and Blogs
 * Page tagging
-* Animated ASCII (Can this be done with minimal JS?)
+* In-line references/extra info
 
 ### Credits
 * Odin

gen.odin

@@ -5,13 +5,6 @@ import "core:fmt"
 import "core:os"
 import "core:strings"
 
-/*
- * WIP files are denoted with an '!' at the start of the file. 
-* This stops the files being processed and uploaded to the site
-* before you finish writing!
-*/
-
-
 BLOG_START_MD := `
 (\
 \'\
@@ -30,6 +23,10 @@ BLOG_TITLE_MD := `
 BLOG_BACK_MD := `
 [<= Back](./..)
 `
+
+// Generates the blog index markdown file (blog/index.md) complete with all
+// current blogs/articles. This is then passed to the 'parse_file_md_to_html'
+// We do this to make updating the blog index much easier
 generate_blog_md_file :: proc(path: string, allocator := context.allocator) {
 	blog_list := make([dynamic]string, allocator)
 	sb := strings.builder_make(allocator)
@@ -39,10 +36,14 @@ generate_blog_md_file :: proc(path: string, allocator := context.allocator) {
 	strings.write_string(&sb, "blog/")
 	blog_dir := strings.to_string(sb)
 
-	//os.write_string(file, BLOG_START)
 	blogs := walk_tree_and_get_md_names(blog_dir, allocator)
 
 	// *********** BLOG PARSING **************
+	/*
+	 * WIP files are denoted with an '!' at the start of the file.
+	* This stops the files being processed and uploaded to the site
+	* before you finish writing!
+	*/
 	for blog in blogs {
 		b := strings.split(blog, blog_dir, allocator = context.temp_allocator)
 		trim_b := strings.trim_right(b[1], ".md")
@@ -68,10 +69,11 @@ generate_blog_md_file :: proc(path: string, allocator := context.allocator) {
 		free_all(context.temp_allocator)
 	}
 
+	// sck: Now we create the index.md file.
 	os.change_directory(blog_dir)
 	index_file, err := os.create("index.md")
 	if err != nil {
-		fmt.eprintfln("ERROR in generate_blog_md_file: Could not open file %s: %s", index_file, os.error_string(err))
+		fmt.eprintfln("ERROR in generate_blog_md_file: Could not create file %s: %s", index_file, os.error_string(err))
 	}
 
 	// sck: final step, write everything in the correct order for the index.html page

main.odin

@@ -8,46 +8,58 @@ import "core:strings"
 import "core:time"
 import fleg "flag"
 
+/* Order of operations:
+ * 1. Generate blog/index.md
+ * 2. Parse ALL .md files into .html files
+ * 3. Write HTML prefixes into .hmtl files
+ * 4. (write fancy timings and footer for main page)
+ */
+
 main :: proc() {
+	// Arena used for ALL allocations, easier to drop everything at end of execution.
 	arena: vmem.Arena
 	arena_err := vmem.arena_init_growing(&arena)
 	ensure(arena_err == nil)
 	arena_alloc := vmem.arena_allocator(&arena)
 	defer vmem.arena_destroy(&arena) //clean up everything!
 
-	fleg.init_custom_allocator(arena_alloc)
+	fleg.init_custom_allocator(arena_alloc) //use arena for flags, why not I made the library!
 	defer fleg.destroy()
 
 	directory: string
 	output_dir: string
-
 	fleg.StringVar(&directory, "dir", "", "input directory of .MD files", required = true)
 	fleg.StringVar(&output_dir, "out", "", "output directory (html files)", required = true)
 	fleg.parse_flags()
 
 	start := time.tick_now() //start timer for footer
 
+	// First generate the blog index file
 	generate_blog_md_file(directory, arena_alloc)
 
+	// Walk directory and collect .md files
 	md_files := walk_tree_and_get_md_names(directory, arena_alloc)
+
+	// ************* MAIN LOOP ************
 	for file, i in md_files {
+		// sck: I am not sure if changing dir's is needed but I am now relying on it lol
 		os.change_directory(directory)
 
+		// turn all .md files into parsed .html files!
 		html, parse_err := parse_file_md_to_html(file, arena_alloc)
 		if parse_err != nil {
-			fmt.eprintfln("ERROR: Could not open file %s: %s", file, os.error_string(parse_err))
+			fmt.eprintfln("ERROR: Could not parse file %s: %s", file, os.error_string(parse_err))
 		}
 
 		filename := strings.split(file, directory, arena_alloc)
 		trimmed_filename := strings.trim_right(filename[1], ".md")
 
-		//Change to output directory. Not sure if this is needed
+		// sck: Change to output directory. Not sure if this also is needed
 		//But messing around with it means I create a lot of
 		//files to clean up. Works for now!
 		os.change_directory(output_dir)
 
-		//print html file name
-		sb := strings.builder_make(arena_alloc) //sb for writing to files, resets ever iteration
+		sb := strings.builder_make(arena_alloc) //sb for writing to files
 		defer strings.builder_destroy(&sb)
 
 		strings.write_string(&sb, fmt.aprintf("%v", trimmed_filename, allocator = arena_alloc))
@@ -62,6 +74,7 @@ main :: proc() {
 
 		write_prefixs_to_html_file(file)
 		os.write_string(file, html) //WRITE PAGE
+
 		//Defer this as we want the last page written to have
 		//accurate timings
 		defer {

parse.odin

@@ -15,6 +15,8 @@ MASTODON_PREFIX :: "<a rel=me href=https://linuxrocks.online/@simonkellet></a>\n
 HIGHLIGHT_JS_PREFIX :: "<script type=\"text/javascript\" src=\"https://unpkg.com/@highlightjs/cdn-assets@11.11.1/highlight.min.js\"></script>\n<script type=\"text/javascript\" src=\"https://unpkg.com/highlightjs-odinlang@1.4.0/dist/odin.min.js\"></script>\n\n<script type=\"text/javascript\">\n  hljs.highlightAll();\n</script>"
 
 
+// Write important HTML prefixes to files. This includes:
+//	- css, utf8, favicon, mastadon and, conditionally, hljs
 write_prefixs_to_html_file :: proc(file: ^os.File) {
 	file_info, err := os.fstat(file, context.temp_allocator)
 	if err != nil {
@@ -34,6 +36,7 @@ write_prefixs_to_html_file :: proc(file: ^os.File) {
 	}
 }
 
+// Walk the tree of the given path and build a string array of all valid .md files
 walk_tree_and_get_md_names :: proc(path: string, allocator := context.allocator) -> [dynamic]string {
 	files := make([dynamic]string, allocator)
 
@@ -65,6 +68,8 @@ walk_tree_and_get_md_names :: proc(path: string, allocator := context.allocator)
 	return files
 }
 
+// sck: INFO: this is currently unused!
+// Taken from: Odin doc from os
 walk_tree :: proc(path: string) -> []u8 {
 	filename: string
 	md_file: []u8
@@ -88,6 +93,9 @@ walk_tree :: proc(path: string) -> []u8 {
 	return nil
 }
 
+// Simply parse all .md files into HTML files (basically where the magic happens)
+// TODO: I think we leak memory here? Each node does not get free'd correctly
+// according to mem's tracking allocator...
 parse_file_md_to_html :: proc(filename: string, allocator := context.allocator, ) -> (parsed: string, err: os.Error) {
 	str := os.read_entire_file_from_path(filename, allocator) or_return
 	root := cm.parse_document_from_string(string(str), cm.DEFAULT_OPTIONS)