diff --git a/clojure/resources/firn/_firn_starter/layouts/default.clj b/clojure/resources/firn/_firn_starter/layouts/default.clj index 644adcc8..6d7893e4 100644 --- a/clojure/resources/firn/_firn_starter/layouts/default.clj +++ b/clojure/resources/firn/_firn_starter/layouts/default.clj @@ -4,6 +4,6 @@ (head [:body [:main - [:article + [:article.content ;; [:div (render :toc)] ;; Optional; add a table of contents [:div (render :file)]]]]))) diff --git a/clojure/resources/firn/_firn_starter/pages/tags.clj b/clojure/resources/firn/_firn_starter/pages/tags.clj index 380b300f..d361f299 100644 --- a/clojure/resources/firn/_firn_starter/pages/tags.clj +++ b/clojure/resources/firn/_firn_starter/pages/tags.clj @@ -1,3 +1,17 @@ (defn tags - [] - [:h1 "Tags"]) + [{:keys [site-tags partials]}] + (let [{:keys [head]} partials] + (head + [:body + [:main + [:article + [:div.content + [:h1 "Tags"] + (for [[tag-name tags] site-tags] + [:div + [:h2 {:id tag-name :class "firn-tag-heading"} tag-name] + (for [tag tags] + [:div + [:a {:href (tag :headline-link)} + (tag :from-file) " - " + (tag :from-headline)]])])]]]]))) diff --git a/clojure/resources/firn/_firn_starter/static/css/firn_base.css b/clojure/resources/firn/_firn_starter/static/css/firn_base.css index 40b5179c..e553570f 100644 --- a/clojure/resources/firn/_firn_starter/static/css/firn_base.css +++ b/clojure/resources/firn/_firn_starter/static/css/firn_base.css @@ -17,9 +17,9 @@ --color-primary: #3498db; --color-primary-accent: #3498db14; --color-bg: #fff; - --color-bg-secondary: #e9e9e9; - --color-secondary: #3498db; - --color-secondary-accent: #3498db0b; + --color-bg-secondary: #eee; + --color-secondary: #f7bb88; + --color-secondary-accent: #db7a3414; --color-shadow: #f4f4f4; --color-text: #444; --color-text-secondary: #999; @@ -27,20 +27,25 @@ --hover-brightness: 1.2; --justify-important: center; --justify-normal: left; - --line-height: 1.5; + --line-height: 1.75; --width-card: 285px; --width-card-medium: 460px; --width-card-wide: 800px; - --width-content: 960px; + --width-content: 860px; /* Currently, Firn only supports 'todo | done' keywords. */ --keyword-active: #2ecc71; /* For "active" Todo keywords. */ --keyword-done: #bdc3c7; /* For "done type keywords" */ --keyword-size: xx-small; + /* Headline priorities ([#A] [#B] etc) */ --priority-a-bg: #c0392b; --priority-b-bg: #3498db; --priority-c-bg: #2ecc71; --priority-size: xx-small; + /* Headline Tags (:my-tag: :unfinished: etc)*/ + --tag-size: small; + --tag-bg: #ecf0f1 + } @@ -50,11 +55,10 @@ --color-primary-accent: #555; --color-bg: #333; --color-bg-secondary: #555; - --color-secondary: #EB9563; - --color-secondary-accent: #EB95630b; --color-shadow: #bbbbbb20; --color-text: #f7f7f7; --color-text-secondary: #aaa; + --tag-bg: #95a5a6; } } @@ -65,6 +69,7 @@ body { color: var(--color-text); font-family: var(--font-family); line-height: var(--line-height); + font-size: 14px; margin: 0; overflow-x: hidden; } @@ -77,6 +82,7 @@ main { .content { max-width: var(--width-content); + margin: 0 auto; } hr { @@ -146,7 +152,6 @@ nav { display: flex; font-weight: bold; justify-content: space-between; - margin-bottom: 7rem; } nav ul { @@ -267,7 +272,7 @@ sup { /* Links */ a { - color: var(--color-secondary); + color: var(--color-primary); display: inline-block; font-weight: bold; text-decoration: none; @@ -452,14 +457,16 @@ table tr:nth-child(even) { } /* Quotes */ + blockquote { display: block; - font-size: x-large; line-height: var(--line-height); - margin: 1rem auto; - max-width: var(--width-card-medium); - padding: 1.5rem 1rem; - text-align: var(--justify-important); + padding: 1rem 1.5rem; + background: var(--color-secondary-accent); + margin: 0; + border-left: 4px solid var(--color-secondary); + max-width: 36rem; + margin: 2rem auto; } blockquote footer { @@ -515,13 +522,6 @@ li > p { } .firn-headline-priority { - /* margin: -22px 8px 0 -6px; */ - /* font-size: 8px; */ - /* min-width: 12px; */ - /* min-height: 12px; */ - /* display: inline-flex; */ - /* justify-content: center; */ - /* align-items: center; */ background-color: var(--color-secondary); border-radius: var(--border-radius); color: white; @@ -569,7 +569,38 @@ li > p { position: relative; } -.firn-headline-timestamp {} +.firn-headline-text { + display: flex; + flex: 1; + align-items: center; +} + + +.firn-tags { + +} + +.firn-tag-heading { + text-transform: capitalize; +} + +.firn-tag { + background-color: var(--tag-bg); + border-radius: var(--border-radius); + color: var(--color-text); + font-size: var(--tag-size); + font-weight: bold; + margin: 0 4px; + padding: 0.2rem 0.4rem; +} + +.firn-tag:hover { + filter: none; +} + +.firn-tag::before { + content: "#"; +} .firn-cookie {} @@ -581,7 +612,9 @@ li > p { /* Org Property Drawers */ -.firn-properties {} +.firn-properties { + background-color: var(--color-bg-secondary); +} .firn-property-key {} @@ -595,7 +628,7 @@ li > p { /* If you choose to render :PROPERTIES: drawers, you may style them: */ .firn-properties { - background: #efefef; + background: var(--color-bg-secondary); padding: 8px; } .firn-property-key {} diff --git a/clojure/resources/firn/_firn_starter/static/css/main.css b/clojure/resources/firn/_firn_starter/static/css/main.css deleted file mode 100644 index 64c53aef..00000000 --- a/clojure/resources/firn/_firn_starter/static/css/main.css +++ /dev/null @@ -1,151 +0,0 @@ -a { - text-decoration: none; - color: #357EDD; -} - -a:visited { - color: #00449E; -} - -pre { - max-width: 100%; - overflow-x: scroll; - padding: 20px; - font-size: 0.8rem; - background: #efefef; -} - -pre code { - margin: 0; - padding: 0px; - font-size: 1em; - background: none; - font-size: 0.9em; - line-height: 1.8; -} - -ul { - padding-left: 16px; - list-style-type: none; - list-style-type: '– '; -} - -li > p { - margin: 8px 0; -} - - -/* Tables */ - -table { - /* Remove spacing between table cells (from Normalize.css) */ - border-collapse: collapse; - border-spacing: 0; - empty-cells: show; - border: 1px solid #cbcbcb; - margin: 32px 0 ; - width: 100%; -} - -table caption { - color: #000; - font: italic 85%/1 arial, sans-serif; - padding: 1em 0; - text-align: center; -} - -table td, -table th { - border-left: 1px solid #cbcbcb; - border-width: 0 0 0 1px; - font-size: inherit; - margin: 0; - overflow: visible; - padding: 0.5em 1em; -} - -table tr:first-child { - background-color: #e0e0e0; - color: #000; - text-align: left; - vertical-align: bottom; -} - - -code { - background: #efefef; - font-size: 0.75em; - padding: 4px 6px; - margin: 0 4px; -} - - -blockquote { - margin: 32px 0; - background: #fafafa; - padding: 12px 24px; - border-left: 4px solid lightgrey; -} - - -hr { - margin: 32px 0; - height: 2px; - background-color: #afafaf; - border: none; -} - -/* Images */ -.firn-img-with-caption {} -.firn-img-caption {} - -img { - width: 100%; -} - -/* Headline Keywords and Priority */ - -.firn-headline-priority { - margin: -22px 8px 0 -6px; - font-size: 8px; - min-width: 12px; - min-height: 12px; - display: inline-flex; - justify-content: center; - align-items: center; -} - - -.firn-headline-priority__A { - color: salmon; -} - -.firn-headline-priority__B { - color: mediumseagreen; -} - -.firn-headline-priority__C { - color: lightblue; -} - -.firn-headline-keyword__DONE { - margin-right: 4px; - color: lightgrey; -} - -.firn-headline-keyword__TODO { - margin-right: 4px; - color: seagreen; -} - -.firn-headline-timestamp {} -.firn-cookie {} - -/* Org Footnotes */ -.firn-footnote-ref {} -.firn-footnote-def {} - -/* Org Property Drawers */ -.firn-properties {} -.firn-property-key {} -.firn-property-value {} diff --git a/clojure/src/firn/build.clj b/clojure/src/firn/build.clj index 92a094b7..f5e1a3d9 100644 --- a/clojure/src/firn/build.clj +++ b/clojure/src/firn/build.clj @@ -78,8 +78,8 @@ [config f] (let [new-file (file/make config f) ; make an empty "file" map. - as-json (->> f slurp org/parse!) ; slurp the contents of a file and parse it to json. - as-edn (-> as-json (json/parse-string true)) ; convert the json to edn. + as-json (->> f slurp org/parse!) ; slurp the contents of a file and parse it to json. + as-edn (-> as-json (json/parse-string true)) ; convert the json to edn. new-file (file/change new-file {:as-json as-json :as-edn as-edn}) ; shadow the new-file to add the json and edn. file-metadata (file/extract-metadata new-file) ; collect the file-metadata from the edn tree. new-file (file/change new-file {:meta file-metadata}) ; shadow the file and add the metadata @@ -103,12 +103,14 @@ @site-map!) -(defn process-all ; org-files - "Receives config, processes all files and builds up site-data - logbooks, site-map, link-map, etc." +(defn process-all ; (ie, just org-files, not pages) + "Receives config, processes all ORG files and builds up site-data logbooks, site-map, link-map, etc. + This is where the magic happens for collecting metadata. Follow the chain: + process-all -> process-one -> file/extract-metadata -> file/extract-metadata-helper" [config] (let [site-links (atom []) site-logs (atom []) + site-tags (atom []) site-map (atom [])] ;; recurse over the org-files, gradually processing them and ;; pulling out links, logs, and other useful data. @@ -121,6 +123,7 @@ :processed-files output :site-map (process-site-map-with-pages! site-map config) :site-links @site-links + :site-tags (into (sorted-map) (group-by :tag-value @site-tags)) :site-logs @site-logs) ;; FIXME: I think we are rendering html twice here, should prob only happen here? with-html (into {} (for [[k pf] output] [k (htmlify config-with-data pf)])) @@ -143,7 +146,8 @@ (when-not is-private (swap! site-map conj new-site-map-item) (swap! site-links concat (-> processed-file :meta :links)) - (swap! site-logs concat (-> processed-file :meta :logbook))) + (swap! site-logs concat (-> processed-file :meta :logbook)) + (swap! site-tags concat (-> processed-file :meta :tags))) ;; add links and logs to site wide data. (recur org-files output)))))) @@ -182,7 +186,7 @@ :site-map site-map :site-links site-links :site-logs site-logs - :site-tags [] ; TODO: collect tags; site-tags + :site-tags site-tags :config config}] (doseq [[k f] pages diff --git a/clojure/src/firn/file.clj b/clojure/src/firn/file.clj index 028a1e14..76483bb1 100644 --- a/clojure/src/firn/file.clj +++ b/clojure/src/firn/file.clj @@ -154,37 +154,50 @@ (loop [tree-data tree-data out-logs [] out-links [] + out-tags [] out-toc [] last-headline nil] ; the most recent headline we've encountered. (if (empty? tree-data) ;; All done! return the collected stuff. {:logbook out-logs :toc out-toc + :tags out-tags :links out-links} ;; Do the work. (let [x (first tree-data) xs (rest tree-data)] (case (:type x) "headline" ; if headline, collect data, push into toc, and set as "last-headline" - (let [toc-item {:level (x :level) - :text (org/get-headline-helper x) + (let [toc-item {:level (x :level) + :text (org/get-headline-helper x) :anchor (org/make-headline-anchor x)} new-toc (conj out-toc toc-item)] - (recur xs out-logs out-links new-toc x)) + (recur xs out-logs out-links out-tags new-toc x)) + + "title" ; if title, collect tags, map with metadata, push into out-tags + (let [headline-link (str "/" + (file-metadata :from-file-path) + (org/make-headline-anchor last-headline)) + headline-meta {:from-headline (org/get-headline-helper last-headline) + :headline-link headline-link} + tags (x :tags) + tags-with-meta (map #(merge headline-meta file-metadata {:tag-value %}) tags) + new-tags (vec (concat out-tags tags-with-meta))] + (recur xs out-logs out-links new-tags out-toc last-headline)) "clock" ; if clock, merge headline-data into it, and push/recurse new-logs. (let [headline-meta {:from-headline (-> last-headline :children first :raw)} log-augmented (merge headline-meta file-metadata x) new-logs (conj out-logs log-augmented)] - (recur xs new-logs out-links out-toc last-headline)) + (recur xs new-logs out-links out-tags out-toc last-headline)) "link" ; if link, also merge file metadata and push into new-links and recurse. (let [link-item (merge x file-metadata) new-links (conj out-links link-item)] - (recur xs out-logs new-links out-toc last-headline)) + (recur xs out-logs new-links out-tags out-toc last-headline)) ;; default case, recur. - (recur xs out-logs out-links out-toc last-headline)))))) + (recur xs out-logs out-links out-tags out-toc last-headline)))))) (defn extract-metadata "Iterates over a tree, and returns metadata for site-wide usage such as @@ -192,14 +205,15 @@ [file] (let [org-tree (file :as-edn) tree-data (tree-seq map? :children org-tree) - file-metadata {:from-file (file :name) :from-file-path (file :path-web)} - keywords (keywords->map file) + keywords (keywords->map file) ; keywords are "in-buffer-settings" + {:keys [date-updated date-created title firn-under firn-order]} keywords + file-metadata {:from-file title :from-file-path (file :path-web)} metadata (extract-metadata-helper tree-data file-metadata) - logbook-sorted (sort-logbook (metadata :logbook) file) ;; TODO - I think sorting this in extract-metadata helper makes more sense. Better internal API. - {:keys [date-updated date-created title firn-under firn-order]} keywords] + logbook-sorted (sort-logbook (metadata :logbook) file)] ;; TODO - I think sorting this in extract-metadata helper makes more sense. Better internal API. {:links (metadata :links) :logbook logbook-sorted + :tags (metadata :tags) :logbook-total (sum-logbook logbook-sorted) :keywords keywords :title title diff --git a/clojure/src/firn/markup.clj b/clojure/src/firn/markup.clj index 7c17d1e4..2f7d9bc4 100644 --- a/clojure/src/firn/markup.clj +++ b/clojure/src/firn/markup.clj @@ -156,8 +156,8 @@ img-http-regex #"(http:\/\/|https:\/\/)(.*)\.(jpg|JPG|gif|GIF|png)" img-rel-regex #"(\.(.*))\.(jpg|JPG|gif|GIF|png)" img-make-url #(->> (re-matches img-file-regex link-href) - (take-last 2) - (s/join ".")) + (take-last 2) + (s/join ".")) ;; file regexs / ctor fns org-file-regex #"(file:)(.*)\.(org)(\:\:\*.+)?" http-link-regex #"https?:\/\/(?![^\" ]*(?:jpg|png|gif))[^\" ]+"] @@ -187,7 +187,6 @@ :else [:a {:href (u/clean-anchor link-href)} link-val]))) - (defn- title->html "Constructs a headline title - with possible additional values (keywords, priorities, timestamps -> can all be found in a headline.) @@ -196,11 +195,13 @@ (let [level (v :level) children (v :children) keywrd (v :keyword) + tags (v :tags) priority (v :priority) properties (v :properties) parent {:type "headline" :level level :children [v]} ; reconstruct the parent so we can pull out the content. heading-priority (u/str->keywrd "span.firn-headline-priority.firn-headline-priority__" priority) heading-keyword (u/str->keywrd "span.firn-headline-keyword.firn-headline-keyword__" keywrd) + heading-tags [:span.firn-tags (for [t tags] [:span [:a.firn-tag {:href (str "/tags#" t)} t]])] heading-anchor (org/make-headline-anchor parent) heading-id+class #(u/str->keywrd "h" % heading-anchor ".firn-headline.firn-headline-" %) h-level (case level @@ -210,19 +211,16 @@ 4 (heading-id+class 4) 5 (heading-id+class 5) (heading-id+class 6)) - make-child #(into [%] (map to-html children))] - (if (and properties (opts :firn-properties?)) - [:div - [h-level - (when keywrd [heading-keyword (str keywrd " ")]) - (when priority [heading-priority (str priority " ")]) - (make-child :span)] - (props->html v)] + make-child #(into [%] (map to-html children)) + render-headline [h-level + (when keywrd [heading-keyword (str keywrd " ")]) + (when priority [heading-priority (str priority " ")]) + (make-child :span.firn-headline-text) + (when tags heading-tags)]] - [h-level - (when keywrd [heading-keyword (str keywrd " ")]) - (when priority [heading-priority (str priority " ")]) - (make-child :span)]))) + (if (and properties (opts :firn-properties?)) + [:div render-headline (props->html v)] + render-headline))) (defn- footnote-ref [v] diff --git a/clojure/test/firn/demo_org/file-metadata.org b/clojure/test/firn/demo_org/file-metadata.org index 986c9292..038d5419 100644 --- a/clojure/test/firn/demo_org/file-metadata.org +++ b/clojure/test/firn/demo_org/file-metadata.org @@ -9,7 +9,7 @@ when a file is parsed. It should: NOTE: Changing this file around will probably break tests. -* A headline with a normal log-book. +* A headline with a normal log-book. :tag1: :LOGBOOK: CLOCK: [2020-01-02 Thu 16:09]--[2020-01-02 Thu 16:20] => 0:11 CLOCK: [2020-04-26 Sun 16:09]--[2020-04-26 Sun 18:20] => 2:11 diff --git a/clojure/test/firn/file_test.clj b/clojure/test/firn/file_test.clj index edc9a425..e92b1175 100644 --- a/clojure/test/firn/file_test.clj +++ b/clojure/test/firn/file_test.clj @@ -70,12 +70,20 @@ (t/testing "Pulls links and logbook entries from a file" (t/is (seq (get-in file [:meta :links]))) (t/is (seq (get-in file [:meta :logbook]))) + (t/is (seq (get-in file [:meta :tags]))) (t/is (= "File Logbook" (get-in file [:meta :title])))) (t/testing "The logbook is associated with a heading." (let [first-entries (-> file :meta :logbook first)] (t/is (= "A headline with a normal log-book." (first-entries :from-headline))))) + (t/testing "The tag is associated with a heading." + (let [first-entries (-> file :meta :tags first)] + (t/is (= "A headline with a normal log-book." (first-entries :from-headline))) + (t/is (= "/file-metadata#a-headline-with-a-normal-log-book" (first-entries :headline-link))) + (t/is (= "File Logbook" (first-entries :from-file))) + (t/is (= "tag1" (first-entries :tag-value))))) + (t/testing "check that logbook gets sorted: most-recent -> least-recent by :start-ts" ;; a clever way (I borrowed) to check if vals in a list are sorted. (t/is (apply >= start-times))))) diff --git a/docs/_firn/pages/tags.clj b/docs/_firn/pages/tags.clj index 66e542b5..6eda0b8f 100644 --- a/docs/_firn/pages/tags.clj +++ b/docs/_firn/pages/tags.clj @@ -1,8 +1,3 @@ -;; (defn tags -;; [{:keys [site-tags partials]}] -;; [:div -;; [:h1 "Tags Page"]]) - (defn render-site-map [sm] (->> sm @@ -10,7 +5,7 @@ (map #(vector :div.pb1 [:a {:href (% :path)} (% :title)])))) (defn tags - [{:keys [site-map site-links partials]}] + [{:keys [site-map site-tags partials]}] (let [{:keys [head nav footer]} partials] (head [:body @@ -20,6 +15,13 @@ [:aside#sidebar.def-sidebar (render-site-map site-map)] [:div.def-content - [:div "This is a temporary page that will be updated in v0.0.7"] - ; (for [x site-map] [:div (str x)]) + [:h1 "Tags"] + (for [[tag-name tags] site-tags] + [:div + [:h2 {:id tag-name :class "firn-tag-heading"} tag-name] + (for [tag tags] + [:div + [:a {:href (tag :headline-link)} + (tag :from-file) " - " + (tag :from-headline)]])]) (footer)]]]]))) diff --git a/docs/_firn/static/css/customization.css b/docs/_firn/static/css/customization.css index c09d714c..ddde7289 100644 --- a/docs/_firn/static/css/customization.css +++ b/docs/_firn/static/css/customization.css @@ -3,6 +3,7 @@ --border-col: #dfdfdf; --nav-bg: #fbfbfb; --nav-bg-inverse: #444; + --nav-height: 54px; } @media (prefers-color-scheme: dark) { @@ -13,6 +14,11 @@ } } +html { + /*For jumping to heading due to the fixed header:*/ + scroll-padding-top: calc(var(--nav-height) + 12px); +} + /* ibm-plex-serif-regular - latin */ @font-face { font-family: 'IBM Plex Serif'; @@ -123,9 +129,9 @@ h2 { align-items: center; background: var(--nav-bg); display: flex; - display: flex; justify-content: flex-end; padding: 8px 0px; + height: var(--nav-height); position: fixed; top: 0; width: 100%; diff --git a/docs/_firn/static/css/firn_base.css b/docs/_firn/static/css/firn_base.css index 0bf2c266..bb54f9d2 100644 --- a/docs/_firn/static/css/firn_base.css +++ b/docs/_firn/static/css/firn_base.css @@ -37,10 +37,15 @@ --keyword-done: #bdc3c7; /* For "done type keywords" */ --keyword-size: xx-small; + /* Headline priorities ([#A] [#B] etc) */ --priority-a-bg: #c0392b; --priority-b-bg: #3498db; --priority-c-bg: #2ecc71; --priority-size: xx-small; + /* Headline Tags (:my-tag: :unfinished: etc)*/ + --tag-size: small; + --tag-bg: #ecf0f1 + } @@ -50,11 +55,10 @@ --color-primary-accent: #555; --color-bg: #333; --color-bg-secondary: #555; - /* --color-secondary: #EB9563; */ - /* --color-secondary-accent: #EB95630b; */ --color-shadow: #bbbbbb20; --color-text: #f7f7f7; --color-text-secondary: #aaa; + --tag-bg: #95a5a6; } } @@ -454,12 +458,11 @@ table tr:nth-child(even) { /* Quotes */ blockquote { display: block; - font-size: x-large; + font-size: large; + font-style: italic; line-height: var(--line-height); - margin: 1rem auto; - max-width: var(--width-card-medium); - padding: 1.5rem 1rem; - text-align: var(--justify-important); + padding: 1.5rem 0; + background: var(--color-primary-accent); } blockquote footer { @@ -515,13 +518,6 @@ li > p { } .firn-headline-priority { - /* margin: -22px 8px 0 -6px; */ - /* font-size: 8px; */ - /* min-width: 12px; */ - /* min-height: 12px; */ - /* display: inline-flex; */ - /* justify-content: center; */ - /* align-items: center; */ background-color: var(--color-secondary); border-radius: var(--border-radius); color: white; @@ -569,7 +565,38 @@ li > p { position: relative; } -.firn-headline-timestamp {} +.firn-headline-text { + display: flex; + flex: 1; + align-items: center; +} + + +.firn-tags { + +} + +.firn-tag-heading { + text-transform: capitalize; +} + +.firn-tag { + background-color: var(--tag-bg); + border-radius: var(--border-radius); + color: var(--color-text); + font-size: var(--tag-size); + font-weight: bold; + margin: 0 4px; + padding: 0.2rem 0.4rem; +} + +.firn-tag:hover { + filter: none; +} + +.firn-tag::before { + content: "#"; +} .firn-cookie {} diff --git a/docs/changelog.org b/docs/changelog.org new file mode 100644 index 00000000..f42cd77c --- /dev/null +++ b/docs/changelog.org @@ -0,0 +1,14 @@ +#+TITLE: Changelog +#+FIRN_ORDER: 8 +#+FIRN_TOC: {:depth 1} + +* V.0.0.7 + +** Feature: Pages +- user's can create "Pages" now. +- Creating a [[file:pages.org][page]] in ~_firn/pages/my_page.clj~ will similar to layouts, convert hiccup to html. +** Feature: Tags and Tag Page +- tags are now displaying in headlines. +- tags in headlines are links to a /tags page, anchored to the respective tag clicked. +- The "tags.clj" page is created out of the box with a new Firn site. +- The tags page lists all tags across all headlines in all files; each a link that jumps to the respective heading. diff --git a/docs/configuration.org b/docs/configuration.org index a88104c1..7a2b4a2e 100644 --- a/docs/configuration.org +++ b/docs/configuration.org @@ -50,7 +50,7 @@ The firn table of contents is rendered in a layout. If you use the default layou :exclusive? true ; Do not render the headline "Notes", just its children. } #+END_SRC -* Reference +* Reference :reference: ** config.edn | Key | Type | Purpose | diff --git a/docs/data-and-metadata.org b/docs/data-and-metadata.org index dc83e3da..25912a7d 100644 --- a/docs/data-and-metadata.org +++ b/docs/data-and-metadata.org @@ -1,6 +1,6 @@ #+TITLE: Data and Metadata #+DATE_CREATED: <2020-03-25 Wed> -#+DATE_UPDATED: <2020-06-24 15:59> +#+DATE_UPDATED: <2020-07-05 17:24> #+FILE_UNDER: docs #+FIRN_LAYOUT: docs #+FIRN_ORDER: 5 @@ -47,6 +47,32 @@ called =:meta= that provides all sorts of metadata available in your file. As the API for accessing file data changes, you can keep an eye on the [[https://github.com/theiceshelf/firn/blob/master/clojure/src/firn/file.clj#L55][file.clj]], source code to see what content is made available at "layout-time". +** Site Tags + +Tags are collected and are grouped by tag name. The structure of the data is as follows: + +#+BEGIN_SRC clojure +{"FAQ" [{:from-headline "Do I have to use layouts?", + :headline-link "/layout#do-i-have-to-use-layouts?", + :from-file "Layout", + :from-file-path "layout", + :tag-value "FAQ" + {:from-headline "How do I customize the styling of my layouts?", + :headline-link "/layout#how-do-i-customize-the-styling-of-my-layouts?", + :from-file "Layout", + :from-file-path "layout", + :tag-value "FAQ"}] + "reference" [{:from-headline "Data and Functions available to layouts", + :headline-link "/layout#data-and-functions-available-to-layouts", + :from-file "Layout", + :from-file-path "layout", + :tag-value "reference"}]} + +#+END_SRC + +Out of the box, Firn provides a basic "Tags" page for displayings headline-tags. +If you do not wish to have a "/tags" page, simply remove it from ~_firn/pages/tags.clj~ + ** Logbook The logbook is collected and sorted by timestamp. The available data looks like so: @@ -243,7 +269,7 @@ after being parsed to JSON and converted to EDN: #+END_SRC -** Interacting with data :revisit: +** Interacting with data As you can see, lots of data. Currently, Firn is not capable of interacting with this data very easily while you develop your Layouts. There are tentative plans diff --git a/docs/getting-started.org b/docs/getting-started.org index 05809808..5e706883 100644 --- a/docs/getting-started.org +++ b/docs/getting-started.org @@ -1,6 +1,6 @@ #+TITLE: Getting Started #+DATE_CREATED: <2020-03-27 Fri> -#+DATE_UPDATED: <2020-06-23 16:13> +#+DATE_UPDATED: <2020-07-05 14:52> #+FIRN_LAYOUT: docs #+FIRN_UNDER: docs #+FIRN_ORDER: 0 @@ -10,7 +10,7 @@ This document describes a step-by-step process to generate a static site with Firn. The author assumes the reader has a working familiarity with the command-line. -*A brief note on Emacs* +** A note on Emacs :emacs: It is almost a safe assumption that if you are here, then you are are already familiar with Org mode, Emacs, Lisp, or all three combined. But that's an assumption. So, for those that consider themselves quite savvy already, you should skip to the [[file:getting-started.org::*Summary][summary]]. @@ -78,6 +78,8 @@ When calling the =firn new= command, a series of folders and files are created: │   │   └── default.clj │   ├── partials │   │   └── head.clj +│   ├── pages +│   │   └── tags.clj │   └── static │   └── css │   └── main.css @@ -135,7 +137,7 @@ Where you will replace ~{My New Heading}~ with the specific headline you have cr Read more about the render function and layouts in the [[file:layout.org][layout document]]. -* Understanding config.edn +* Understanding config.edn :configuration: When generating a new site, Firn will create a =config.edn= file in the =_firn= directory. This file covers several different aspects of customization for the building of your site. Making changes to this file will largely affect the build output of Firn, as well as rendering behaviour across all files. @@ -157,7 +159,7 @@ links in org-files, a user can change the =dir-data= key to point to the folder The available configuration keys are commented within the file itself, and are more heavily documented in the [[file:configuration.org][configuration documentation]]. Beyond the above example, the functionality of this file is out of scope for the getting started guide. -* Adding attachments +* Adding attachments :attachments: The above example largely describes how to use "attachments" (ie, a folder with images etc). Set the name of your folder where images/files are linked to, and it will copy the contents over. diff --git a/docs/index.org b/docs/index.org index fdccdf84..1cca5bec 100644 --- a/docs/index.org +++ b/docs/index.org @@ -1,6 +1,6 @@ -#+TITLE: Index +#+TITLE: Home #+DATE_CREATED: <2020-03-24 Tue> -#+DATE_UPDATED: <2020-06-25 09:50> +#+DATE_UPDATED: <2020-07-05 17:28> #+FILE_UNDER: docs #+FIRN_LAYOUT: index #+FIRN_ORDER: 1000 @@ -54,7 +54,7 @@ When you create and build a Firn site, the following happens: ----- -** FAQ +** FAQ :FAQ: *** Will Windows be supported? diff --git a/docs/layout.org b/docs/layout.org index 50ab200d..5fa67a58 100644 --- a/docs/layout.org +++ b/docs/layout.org @@ -1,6 +1,6 @@ #+TITLE: Layout #+DATE_CREATED: <2020-03-24 Tue> -#+DATE_UPDATED: <2020-07-03 18:21> +#+DATE_UPDATED: <2020-07-05 14:55> #+FILE_UNDER: docs #+FIRN_LAYOUT: docs #+FIRN_ORDER: 2 @@ -10,8 +10,7 @@ When you create a new Firn site for the first time, it will create a folder: =_firn/layouts=. The layout folder stores Clojure files (=.clj=) that are responsible for how your org-file is rendered to-html; The act of "applying" a -template means to pass the content of the org-file through a specific [[https://github.com/weavejester/hiccup][clojure -hiccup]] template that organizes how the content is displayed. +template means to pass the content of the org-file through a specific [[https://github.com/weavejester/hiccup][clojure hiccup]] template that organizes how the content is displayed. When an org-mode file is processed by Firn it looks for the in-buffer-setting ~#+FIRN_LAYOUT:~ to see if it uses a Layout. If none are specified, the _default @@ -69,14 +68,14 @@ Inside docs.clj place the following clojure code. *NOTE:* Layouts can have multiple Clojure functions in them, however only the last function of the file will be applied as the layout. -* Do I have to use layouts? +* Do I have to use layouts? :FAQ: Not exactly. When you create a new Firn site, it will have a =default.clj= file in the =layouts= directory. This provides a very basic out of the box formatting and will render the entirety of your org mode file. If you want to add any kinds of customization - even css, you'll need to work with layouts. -* How do I customize the styling of my layouts? +* How do I customize the styling of my layouts? :FAQ: As with normal HTML, you'll need to add a =head= tag with a =link= that references to a css file. It might make sense for you to create a partial for defining your @@ -191,8 +190,7 @@ There are several ways you can create table of contents in your files, from simp #+FIRN_TOC: {:depth 4} #+END_SRC - -* Data and Functions available to layouts +* Data and Functions available to layouts :reference: The following keys are made available in your layouts. @@ -252,31 +250,14 @@ The above template only needs access to =render=, =partials= and the =logbook=. #+END_SRC - -* Styling Layouts +* Styling Layouts :styling: You can write css as you normally would by placing css files in the =_firn/static/css= folder and then having =firn= move them into your =_site= folder when run. Styling is applied through [[https://github.com/weavejester/hiccup#syntax][hiccup]]. There are some internal styles that are applied when org-mode text is -transformed into data. These styles are all prefaced with the keyword =firn_=, (ie -=firn_title-prirority= or =firn_title-keyword=). - -The following are the css classes and their rerspective org-mode structure they -augment, as they come hard-coded into firn: - -| Css class | Element | -|---------------------------------+---------------------------------------------| -| .firn_title-priority | Title Priority (ex: [#A] / [#B] etc) | -| .firn_title-priority__A | Targets =[#A]= | -| .firn_title-priority__B | Etc. | -| .firn_title-priority__C | Etc. | -| .firn_title-keyword | Targets all keywords =TODO/DONE= etc. | -| .firn_title-keyword__TODO | Targets =TODO= | -| .firn_title-keyword__DONE | Targets =DONE= | -| .firn-headline-timestamp | Headline Timestamps* | -| .firn-headline-cookie | Targets headline todo-count (ex =[7/10]=) | -| .firn-headline-section | A "*" container and it's contents | -| .firn-headline-section-${level} | Target specific headline+container by level | -| .firn-headline-${1-6} | Target h1-h6 | +transformed into data. These styles are all prefaced with the keyword ~firn-~, (ie. +=firn-headline-text= or =firn-tag=). + +Inspect the file ~_firn/static/css/firn_base.css~ to see the configurable elements. diff --git a/docs/limitations.org b/docs/limitations.org index d458e506..4ff2fec3 100644 --- a/docs/limitations.org +++ b/docs/limitations.org @@ -1,13 +1,14 @@ #+TITLE: Limitations #+DATE_CREATED: <2020-03-27 Fri> -#+DATE_UPDATED: <2020-07-03 18:22> +#+DATE_UPDATED: <2020-07-05 17:27> #+FIRN_ORDER: 6 * Development Server -The file watcher (reloading of files on change) is a bit slow. +- The file watcher (reloading of files on change) is a bit slow. +- Certain site-wide data/metadata collected happens at the initial compile time. Things like the site-logs, site-map, site-links *do not* get updated when a single file is updated when using the development server. You will need to re-start the server to re-process the files. -* Attachments +* Attachments :attachments: - Currently, Firn copies the _entirety of this folder into your build output_. This means that if you have attachments which are private or simply unlinked to from org-files, they will be included in your build output. - Org-attach links are not supported. diff --git a/docs/pages.org b/docs/pages.org index bfb488c6..70e6339e 100644 --- a/docs/pages.org +++ b/docs/pages.org @@ -1,6 +1,6 @@ #+TITLE: Custom Pages #+DATE_CREATED: <2020-03-24 Tue> -#+DATE_UPDATED: <2020-07-03 18:35> +#+DATE_UPDATED: <2020-07-05 15:07> #+FILE_UNDER: docs #+FIRN_LAYOUT: docs #+FIRN_ORDER: 3 @@ -9,23 +9,23 @@ Similar to [[file:layout.org][layouts]], on creating a Firn site, you will find a folder: =_firn/pages=. This folder enables users to create custom pages that are converted from the template language (hiccup) into HTML. This is useful if you want to create a page that does not render any org-mode content. -* TODO Tags - an out of the box page. - -The following will be available in v0.0.7 +* Tags - an out of the box page Creating a new firn site comes with a custom page: =tags.clj=. This file exists to provide an example of a custom page, as well as to give user's an out-of-the-box solution for rendering tags with Firn. When Firn processes your org-mode files, it collects all heading tags, and stores them in a Clojure vector (simply, a list). This list of tags are made available to layouts and pages - in this case, the latter, which uses it to render all the tags your org-mode content has. You can of course delete this file if you do not want to render tags. -* TODO Differences from layouts +* Differences from layouts Pages have less data available to them at site-generation time. Because there are no org-mode files concerned, there is no =render= function. The following content is available to a page, which like layouts, can be destructured and made available to your Clojure hiccup function. -| Function/Data | Intent | Data-type | -|---------------+--------------------------------------------+-----------| -| config | The site wide config | map | -| partials | a list of invokable partials =/partials= dir | list | -| site-links | A list of all links across all documents | vector | -| site-logs | A list of all logbook entries | vector | -| site-map | A list of all files on the wiki | vector | +| Function/Data | Intent | Data-type | +|---------------+--------------------------------------------+-------------------| +| config | The site wide config | map | +| partials | a list of invokable partials =/partials= dir | list | +| site-links | A list of all links across all documents | vector | +| site-logs | A list of all logbook entries | vector | +| site-map | A list of all files on a site | vector | +| site-tags | A list of all tags across all org files | map (string<>list) | + * Limitations ** Metadata diff --git a/docs/sample-page.org b/docs/sample-page.org index cfef3b5c..d1a3691b 100644 --- a/docs/sample-page.org +++ b/docs/sample-page.org @@ -222,9 +222,9 @@ Tables are converted into HTML tables: | Pacific | 165,250,000 km2 | | Southern | 20, 330,000 km2 | -** TODO Tags :upcoming: +** Tags :example: -Tags are not yet supported, but will be developed soon. +Headlines with ~:tags:~ will automatically create a tag on the right of the heading that links to a ~/tags~ page. The tags.clj page can be found in ~_firn/pages/tags.clj~ and can be edited. ** Org Dates