Please add ./examples/ directory

[holtzermann17]

Hi, it would be useful to have some examples that Firn users have come up with.

As an example-of-an-example, here's a layout I set up for blog updates:

blog.clj

(defn blog
  [{:keys [build-url title render partials]}]
  (let [{:keys [head]} partials]
    [:html
     (head build-url)
     [:body
      [:main
       [:article.def-wrapper
        [:div.def-content
         [:h1 title]
         ;; List files that are "FIRN_UNDER" the "Updates" page
         ;; But only those which are immediately "under" it
         ;; sorted by newness
         (render :sitemap {:start-at ["Updates"]
                           :depth 1
                           :sort-by :newest})
         [:hr]
         [:div.back-to-main
          [:p "Back to main index: "
           [:a {:href "https://exp2exp.github.io/index.html"} "Exp2Exp"]]]
         ]]]]]))

And here's how the individual blog updates look:

update.clj

(defn update
  [{:keys [render partials title meta date-created build-url]}]
  (let [{:keys [head]} partials]
    [:html
     (head build-url)
     [:body
      [:main
       [:article.content
        ;; [:div (render :toc)] ;; Optional; add a table of contents
        [:h1 title]
        [:i (str date-created " — " (-> meta :keywords :author))]

        [:div (render :file)]
        ;; if backlinks exist, store them in a let bindings.
        (when-let [backlinks (render :backlinks)] 
          [:div
           [:hr]
           [:div.backlinks
            [:h4 "Backlinks to this document:"]
            backlinks]])
        [:hr]
        [:div.back [:p "Back to blog: " [:a {:href "https://exp2exp.github.io/updates.html"} "Exp2Exp: Updates"]]]]]]]))

I'd be happy to contribute these (or adjusted variants) to the examples dir when it's ready.

[teesloane]

I added a layout examples - do you mind adding your examples to the org doc? Try and comment the example thoroughly and leave out any unnecessary parts. I think the second example would best be referred to as "How to use custom keywords" and then you may remove the backlinks, etc.

[holtzermann17]

@teesloane Yes, happy to add that.

Would it be good to create a separate page with "deployment examples"? Maybe this is pushing the limit of what really fits inside Firn's docs, since it's so dependent on the downstream environment. On the other hand, such examples might be useful.

It took me a while to update this Github Actions Workflow

• https://github.com/exp2exp/exp2exp.github.io/blob/master/.github/workflows/src-build.yml written by @cameronraysmith to work in a slightly different setting:
• https://github.com/PeeragogyLabs/PeeragogyORG/blob/main/.github/workflows/firn.yml (Also Github Actions, but now in the gh-pages branch of an "arbitrary" repository.)

Some distilled version of these might fit well in here: https://github.com/peaceiris/actions-gh-pages#examples with a cross-reference from inside Firn's docs.

[teesloane]

Ah sorry, I missed your reply.

I'm going to leave deployment out of docs for now as it's pretty user-case dependent (one might vendor the binary into their CI process, another might just build raw html files and upload those to a server etc) and would make for additional documentation maintenance. Also, the github-actions for the site deployment might be sufficient to see how Firn's documentation is deployed with github pages.

Also! I'll close this since https://github.com/theiceshelf/firn/commit/3acb597535d3ee685d737545c818cb764b4552ab added examples :)

[NightMachinery]

Adding something like https://ox-hugo.scripter.co/doc/examples/ will be great.

[teesloane]

Thanks for the suggestion. I will think about this.