From 993f0d5db6c2a1285c15a20f23af23a3913cd9b5 Mon Sep 17 00:00:00 2001 From: Kyle Bowman Date: Sat, 23 Nov 2024 17:27:06 -0500 Subject: [PATCH] chore: make demo better. * Adds an about page * Moves style-based acknowledgements into the demo * Recreates sakura's HTML/CSS demo page as markdown --- src/demo/about.md | 73 +++++++++++++++++ .../demo/acknowledgements.md | 2 +- src/demo/demo.md | 78 +++++++++++++++++++ src/demo/note1.md | 6 -- src/demo/note2.md | 6 -- 5 files changed, 152 insertions(+), 13 deletions(-) create mode 100644 src/demo/about.md rename acknowledgements.md => src/demo/acknowledgements.md (87%) create mode 100644 src/demo/demo.md delete mode 100644 src/demo/note1.md delete mode 100644 src/demo/note2.md diff --git a/src/demo/about.md b/src/demo/about.md new file mode 100644 index 0000000..6058c71 --- /dev/null +++ b/src/demo/about.md @@ -0,0 +1,73 @@ +--- +title: About the Project +author: Kyle Bowman +created: 20241123084949 +last_updated: 20241123084949 +--- + +[Pandoc](https://pandoc.org/) deserves to be mentioned before Jetsam as it's the +real workhorse of this operation. Jetsam can be described as a Pandoc-based +distribution of writing utilities designed to help you write, publish, and +maintain a corpus of personal-space writings. + +# About Personal-Space Writing and Jetsam Philosophy + +Personal-space writing is an *ad hoc* term designed to connote your own cozy part +of the web. It's intended to contrast with enterprise- or commercial-style +writing. For example, personal-space writing is more aligned to capturing one +person's thoughts over a lifetime than it is to maximizing reader engagement. + +The following principles of personal-space writing help govern the philosophy of the Jetsam project: + +* **Prioritize simple data formats.** Data tends to outlast your application, so +choose something that won't lock you in. Either the format should be relevant +in 20 years or you should be able to be easily port it to whatever is relevant in +20 years. +* **Next, prioritize predicably stable tools.** Even if you choose a simple data +format, each application tends to have its own quirks about how it handles the +data. When you accumulate a volume of data, migrating becomes non-trivial even +for small deviations. Each new dependency incurs a maintenance cost, so it deserves +scrutiny. When you add a new dependency, try to +[Choose Boring Technology](https://mcfunley.com/choose-boring-technology) as the +maintenance risk of __ tends to be much lower than __. +* **Then, prioritize extensibility.** Ostensibly, a personalized space is the +goal. So, why is it last in this list of priorities? Because, if you don't +have the stability offered by the previous priorities, you'll spend an awful +lot of time rebuilding your extensions. But you can innovate a lot _on top of_ +boring technology. + +With those guidelines in mind, you can see why we rely so heavily on Pandoc. + +* **We can use Markdown as our primary data format.** Markdown is a simple +standard, which makes it easy to create tools for. Furthermore, it's a text- +based standard, so if all else fails, it's still readable. +* **Pandoc is its own data migration tool.** This includes migrating between +different flavors of Markdown. +* **Pandoc is relatively stable with ongoing support.** There have been 3 major +releases in its first 18 years. The core seems pretty stable. There are still +updates every few days. But even if the project becomes unmaintained, the +existing versions contain a _ton_ of functionality. Its infinitely stable +in that regard. +* **Pandoc contains an embedded Lua interpreter.** This gives you a ton of +room for extensibility without adding potentially fragile dependencies. + +# About the Name + +The term [jetsam](https://en.wikipedia.org/wiki/Flotsam,_jetsam,_lagan_and_derelict#Jetsam) +comes from maritime law. It refers to cargo that is intentionally discarded +from a ship or wreckage. Jetsam is often the byproduct of trying to save a +sinking ship by reducing its load. Per maritime law, someone that recovers jetsam +is generally not obligated to return it to the original owner. The finder retains +the value of the recovered goods. + +Jetsam is a beautiful metaphor for writing. For the writer, writing is a powerful form of [rubber ducking](https://en.wikipedia.org/wiki/Rubber_duck_debugging) +(jetsam's mascot). Writing forces you to encounter and clarify any ambiguous or +underspecified thoughts that you may have about a topic. Once you have written +about the topic sufficiently clearly, it _feels_ resolved. You can mentally offload +it. But just because you discard it doesn't mean that your jetsam isn't valuable to +whomever stumbles upon it. + +Also, I chuckle at the mental image of a panicked sailor casting rubber ducks off a +sinking ship. + +Godspeed, little ducky. \ No newline at end of file diff --git a/acknowledgements.md b/src/demo/acknowledgements.md similarity index 87% rename from acknowledgements.md rename to src/demo/acknowledgements.md index fbc68b8..758b6d1 100644 --- a/acknowledgements.md +++ b/src/demo/acknowledgements.md @@ -11,4 +11,4 @@ This site is heavily influenced by the following projects: | Normalize CSS | https://github.com/necolas/normalize.css | [MIT License](https://github.com/necolas/normalize.css/blob/master/LICENSE.md) | | Vim Deep Space | https://github.com/tyrannicaltoucan/vim-deep-space/ | [MIT License](https://github.com/tyrannicaltoucan/vim-deep-space/blob/master/LICENSE) | -Thank you for your contributions to the open source community! \ No newline at end of file +Thank you for choosing to open-source your contributions to the open source community! \ No newline at end of file diff --git a/src/demo/demo.md b/src/demo/demo.md new file mode 100644 index 0000000..34e144a --- /dev/null +++ b/src/demo/demo.md @@ -0,0 +1,78 @@ +--- +title: Demo Page +author: Kyle Bowman +created: 20241123170613 +last_updated: 20241123170613 +--- + +This page demonstrates how various Markdown elements are rendered and the +style that is applied. It is useful as a suite of tests when you tinker. + +# Demo + +This is an anchor tag/hyperlink: [sakura - GitHub Repository](https://github.com/oxalorg/sakura). + +Paragraphs look like this. Font size along with line height and maximum width +are optimized for reading. + +_Italic_, **strong**, and `monospace`. Itemized lists look liked: + +* this one +* that one +* the other one + +Here's a block quote: + +>Man surprised me most about humanity. Because he sacrifices his health in order +to make money. Then he sacrifices money to recuperate his health. And then he is +so anxious about the future that he does not enjoy the present; the result being +that he does not live in the present or the future; he lives as if he is never +going to die, and then dies having never really lived. -James J Lachard + +## An h2 header + +Some code blocks: + +``` python +def foobar(): + return "Welcome to flavor country!" +``` +### An h3 header + +A nested list: + +1. First, get these ingredients + * carrots + * celery + * lentils +2. Boil some water. +3. Dump everything in the pot and follow this algorithm: + +``` +uncover pot +stir +cover pot +balance wooden spoon precariously on pot handle +wait 10 minutes +goto first step (or shut off burner when done) +``` + +Do not bump wooden spoon or it will fall + +# Header level 1 +## Header level 2 +### Header level 3 +#### Header level 4 +##### Header level 5 +###### Header level 6 + +A horizontal line: + +--- + + + +Here's a link to [my acknowledgements for the demo](../demo/acknowledgements.md). +You can see what tables look like on that page. + + diff --git a/src/demo/note1.md b/src/demo/note1.md deleted file mode 100644 index 9663da6..0000000 --- a/src/demo/note1.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Note 1 -author: Kyle Bowman ---- - -This is a note that links to [[note2]]. \ No newline at end of file diff --git a/src/demo/note2.md b/src/demo/note2.md deleted file mode 100644 index 2851e55..0000000 --- a/src/demo/note2.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Note 2 -author: Kyle Bowman ---- - -This is a note that links to [[note1]]. \ No newline at end of file -- 2.39.5