From 990a9a1bb940ded5ac1586b3420083b2aad2a0a0 Mon Sep 17 00:00:00 2001
From: Facundo Olano <facundo.olano@gmail.com>
Date: Wed, 21 Feb 2024 14:32:03 -0300
Subject: [PATCH] Improve README examples (#10)

* tweak init output

* add draft flag to default front matter

* add acknowledgements

* remove draft mentions until we add support for it

* add comments between commands
---
 README.md            | 99 +++++++++++++++++++++++++++++++-------------
 commands/commands.go |  5 ++-
 2 files changed, 74 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 629b658..63b82cd 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,6 @@
 # jorge
 A personal (small + opinionated) site generator with [org-mode](https://orgmode.org/) (and markdown) support.
 
-(NOTE: this is stil a WIP, the doc below is a wishlist, not the current behavior.)
-
 ## Installation
 Download the [latest release binary](https://github.com/facundoolano/jorge/releases/latest) for your platform, for example:
 
@@ -13,46 +11,81 @@ Alternatively, install with go:
 
     $ go install github.com/facundoolano/jorge@latest
 
-## Usage
+## Example usage
+
+Create a new website with `jorge init`:
 
 ```bash
 $ jorge init myblog
-> site name: My Blog
-> author: Facundo Olano
-> url: https://myblog.olano.dev
+site name: My Blog
+site url: https://myblog.olano.dev
+author: Facundo Olano
+added myblog/.gitignore
+added myblog/includes/post_preview.html
+added myblog/layouts/base.html
+added myblog/layouts/default.html
+added myblog/layouts/post.html
+added myblog/src/assets/css/main.css
+added myblog/src/blog/goodbye-markdown.md
+added myblog/src/blog/hello-org.org
+added myblog/src/blog/index.html
+added myblog/src/blog/tags.html
+added myblog/src/feed.xml
+added myblog/src/index.html
+```
 
-  added myblog/README.md
-  added myblog/.gitignore
-  added myblog/config.yml
-  added myblog/layouts/base.html
-  added myblog/layouts/post.html
-  added myblog/src/index.html
-  added myblog/assets/css/main.css
-  added myblog/src/blog/hello.org
-  added myblog/src/feed.xml
-  added myblog/src/tags.html
+This initializes a new project with default configuration, styles and layouts, and a couple of sample posts.
+(You can, of course, use a different site structure or just skip the init command altogether).
 
+To preview your site locally, use `jorge serve`:
+
+```bash
 $ cd myblog
-$ jorge post "My First Post"
-  added draft src/blog/my-first-post.org
-
-# serve the site locally with live reload
 $ jorge serve
-  server running at http://localhost:4001/
+wrote target/feed.xml
+wrote target/blog/goodbye-markdown.html
+wrote target/blog/my-first-post.html
+wrote target/blog/hello-org.html
+wrote target/blog/index.html
+wrote target/index.html
+wrote target/blog/tags.html
+server listening at http://localhost:4001
+```
 
-# browse to the new post
-$ open http://localhost:4001/blog/my-first-post
+The site is renders the files found at `src/` in the `target/` directory.
+You can add new pages by just adding files to `src/` but, for the common case of adding blog posts,
+the `jorge post` creates files with the proper defaults:
 
-# add some content
-$ cat >> src/blog/test.org <<EOF
+```
+$ jorge post "My First Post"
+added src/blog/my-first-post.org
+$ cat src/blog/my-first-post.org
+---
+title: My First Post
+date: 2024-02-21 13:39:59
+layout: post
+lang: en
+tags: []
+---
+#+OPTIONS: toc:nil num:nil
+#+LANGUAGE: en
+```
+
+(Posts are created as .org files by default, but you can chage it to prefer markdown or another text format).
+
+If you still have `jorge serve` running, you can see the new post by browsing to `http://localhost:4001/blog/my-first-post`. You can then add some content and the browser tab will automatically refresh to reflect your changes:
+
+```bash
+$ cat >> src/blog/my-first-post.org <<EOF
 *** Hello world!
 
 this is my *first* post.
 EOF
+```
 
-# remove the draft flag before publishing
-$ sed -i '/^draft: true$/d' src/blog/my-first-post.org
+Finally, you can render a minified version of your site with `jorge build`:
 
+```
 $ jorge build
   wrote target/index.html
   wrote target/assets/css/main.css
@@ -62,8 +95,18 @@ $ jorge build
   wrote target/tags.html
 ```
 
-For more details see the:
+And that's about it. For more details see the:
 
   - [Tutorial](https://jorge.olano.dev#tutorial)
   - [Docs](https://jorge.olano.dev#docs)
   - [Development blog](https://jorge.olano.dev#blog)
+
+## Acknowledgements
+
+jorge started as a Go learning project and was largely inspired by [Jekyll](https://jekyllrb.com/). Most of the heavy lifting is done by external libraries:
+
+* [osteele/liquid](https://github.com/osteele/liquid) to render liquid templates. Some Jekyll-specific filters were copied from [osteele/gojekyll](https://github.com/osteele/gojekyll/).
+* [niklasfasching/go-org](https://github.com/niklasfasching/go-org) to render org-mode files as HTML.
+* [yuin/goldmark](https://github.com/yuin/goldmark) to render Markdown as HTML.
+* [go-yaml](https://github.com/go-yaml/yaml) to parse YAML files and template headers.
+* [tdewolff/minify](https://github.com/tdewolff/minify) to minify HTML, CSS, XML and JavaScript files.
diff --git a/commands/commands.go b/commands/commands.go
index 726fce4..dadd278 100644
--- a/commands/commands.go
+++ b/commands/commands.go
@@ -55,6 +55,7 @@ func Init(projectDir string) error {
 	siteName := Prompt("site name")
 	siteUrl := Prompt("site url")
 	siteAuthor := Prompt("author")
+	fmt.Println()
 
 	// creating config and readme files manually, since I want to use the supplied config values in their
 	// contents. (I don't want to render liquid templates in the WalkDir below since some of the initfiles
@@ -98,7 +99,7 @@ func Init(projectDir string) error {
 		if err != nil {
 			return err
 		}
-		fmt.Println("added", path)
+		fmt.Println("added", targetPath)
 		return targetFile.Sync()
 	})
 }
@@ -142,7 +143,7 @@ func Post(root string, title string) error {
 	if err := os.WriteFile(path, []byte(content), FILE_RW_MODE); err != nil {
 		return err
 	}
-	fmt.Println("added", path)
+	fmt.Println("added draft", path)
 	return nil
 }