ro 1.4.6 → 4.4.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NGU2NmU2NTUwNTgxZmM3OTUwYzYzNmFiZWQ3NzMyYzc3YmE0ODM2OQ==
-  data.tar.gz: !binary |-
-    YWM3ZjJhOWRmMWZiZWRlZmFmZWMzNTM1NzRlNzNkZTFkZmMxMzFmZA==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    NmQ3Y2U2NTk3NWJhM2MyY2E0MmE2NWRkZWMwOGUwMGI3ZjMwZjgyNjI1ZjZk
-    NjI1NTJmZWExMzQ5YmY4M2ExZDUwZTE2OTI5NWY3YjM4ODkxNDk1YTc3ZDYw
-    NTZmODg5MjRlYTQzN2MxZGY1NGQxNDk3N2ZlODA5OWNiMGIxMjQ=
-  data.tar.gz: !binary |-
-    ODU5MWMwODIyNTM0NzdhMmFlMjczNjUyNWZjMTdmYzFkMmEwYmMwMWY0ZWUw
-    NTQ5NTE3ZTU0NzUyZTcyM2QyNTFhOTUzYWNlMjhkMzE4Y2JhZjJlMWYwMDM5
-    MGY4NDQxNzQ4NzcwMWIwZDA2MWE3NDFhYzgzOTIyNmJhNTBlMjM=
+SHA256:
+  metadata.gz: 9b56a7cf51b2b6e2140b3be71875fe284e77a59d0e7fa108fd45d39369aba51b
+  data.tar.gz: 02da6783adba57026d22c2e95841ad3b3acc4979c538bd86896b7f293037178b
+SHA512:
+  metadata.gz: b704d4f58a18df10308884c353dc05293d294d46ddfb46b8241e5047691500dcf5471f5dac5522a8126e59885c61b49fd03deba036e54db6f2191145706f0450
+  data.tar.gz: 3bcf32a9c1096c33c898b582f4d038625771c44203ce49792017d07b097285327ce6e90f0c3136bfdda1e185c0d826a50eefbf377dfd2e6e9fc126b8bfed80bf

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,64 @@
+PATH
+  remote: .
+  specs:
+    ro (4.2.1)
+      ak47 (~> 0.2)
+      image_size (~> 3.0)
+      kramdown (~> 2.4, >= 2.4.0)
+      kramdown-parser-gfm (~> 1.1, >= 1.1.0)
+      map (~> 6.6, >= 6.6.0)
+      rouge (~> 4.1, >= 4.1.1)
+      webrick (~> 1.8.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ak47 (0.2.5)
+      guard (~> 0.10.0)
+      shell_tools (~> 0.1.0)
+      smart_colored
+    ffi (1.17.0)
+    ffi (1.17.0-aarch64-linux-gnu)
+    ffi (1.17.0-aarch64-linux-musl)
+    ffi (1.17.0-arm-linux-gnu)
+    ffi (1.17.0-arm-linux-musl)
+    ffi (1.17.0-arm64-darwin)
+    ffi (1.17.0-x86-linux-gnu)
+    ffi (1.17.0-x86-linux-musl)
+    ffi (1.17.0-x86_64-darwin)
+    ffi (1.17.0-x86_64-linux-gnu)
+    ffi (1.17.0-x86_64-linux-musl)
+    guard (0.10.0)
+      ffi (>= 0.5.0)
+      thor (~> 0.14.6)
+    image_size (3.4.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    map (6.6.0)
+    rexml (3.3.9)
+    rouge (4.4.0)
+    shell_tools (0.1.2)
+    smart_colored (1.1.1)
+    thor (0.14.6)
+    webrick (1.8.2)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  ro!
+
+BUNDLED WITH
+   2.5.22

data/LICENSE

@@ -0,0 +1 @@
+Nonstandard

data/README.md

@@ -1,170 +1,341 @@
-NAME
-----
+TL;DR:
+------
+
+`ro` stands for `read only`, and it is the tiniest, best, headless cms.
+
+it lets you keep all your content in github, as god intended.
+
+it is one part cms, one part database, one part api, and one part magic.
+
+if you used a headless cms, it's like that, before they existed, except way better, and free.
+
+with `ro`, you can seperate your content from presentation, like a sane and decent human being.
+
+> silent code whispers
+> github's gentle, peaceful hush
+> simplicity reigns
+
+README
+------
+
+`ro` is has been in professional, production use for over a decade, powering
+many, many websites built by http://dojo4.com, and others.
+
+from static sites, to rails monoliths, to simple ruby sites, to javascript
+sites built on next.js, `ro` is the portable, simple, future-proof content
+system you always dreamed about then started to write but found out the web is
+a mess.
+
+with `ro`, your shit will be *clean*.
 
-ro
+---
+
+to grok `ro` it is best to start with an example of some real content,
+for a real site.
 
 
-TL;DR
------
+```sh
 
-<pre>
+  drawohara@drawohara.dev:ro[main] #=> tree public/ro/posts/almost-died-in-an-ice-cave/
+  public/ro/posts/almost-died-in-an-ice-cave/
+  ├── assets
+  │   ├── image1.png
+  │   ├── image2.png
+  │   ├── image3.png
+  │   ├── og.jpg
+  │   └── purple-heart.jpg
+  ├── attributes.yml
+  └── body.md
+
+```
 
-    ro
-    ├── people
-    │   ├── ara
-    │   │   ├── assets
-    │   │   │   ├── ara-glacier.jpg
-    │   │   │   └── source
-    │   │   │       └── a.rb
-    │   │   ├── attributes.yml
-    │   │   └── bio.md.erb
-    │   └── noah
-    │       └── attributes.yml
-    └── posts
-        ├── foobar
-        ├── hello-world
-        │   ├── attributes.yml
-        │   └── body.md
-        └── second-awesome-post
-            ├── attributes.yml
-            └── body.md
+in this example you can see a few things, regarding the layout of a `ro` directory:
 
-</pre>
+- `ro` content often, but is not required, to live in `public`.  more on this below.
 
+- the essential layout is
 
 ```ruby
 
-  ro
-    #=> all the content nodes
+    @root       = "ro"
+    @collection = "posts"
+    @id          = "almost-died-in-an-ice-cave"
 
-  ro.posts
-    #=> all the post nodes
+    "#{ @root }/#{ @collection }/#{ @id }"
 
-  ro.people                                 
-    #=> all people nodes
+```
 
-  ro[:people]                               
-    #=> same thing
+if you learn best by example, you can examine the `ro` directory of my own website here -> https://github.com/ahoward/drawohara.io/tree/main/public/ro
 
-  ro.people.ara                             
-    #=> data for the person named 'ara'
+- several environment variables control how `ro` works, most notably
 
-  ro[:people][:ara]                         
-    #=> same thing
+```ruby
 
-  ro['people']['ara']                         
-    #=> same thing
+  # this is the fs root of all ro content
+  #
 
-  ro.people.ara.first_name                  
-    #=> give you *one* guess ;-) !
+  Ro.root = ENV['RO_ROOT'] || './public/ro'
 
-  ro.people.ara.url_for('ara-glacier.jpg')  
-    #=> external timestamped  url for this asset
+  # this is the url where ro content, especially images, will be expected to
+  # live at when live
 
-  ro.people.ara.source('a.rb')              
-    #=> syntax highlighted source yo!
+  Ro.url = ENV['RO_URL'] || '/ro'
 
-  ro.posts.find('second-awesome-post').body 
-    #=> html-z yo
+```
 
-  ro.people.ara.related(:posts)             
-    #=> all related posts
+more about this can be rtfm'd here -> https://github.com/ahoward/ro/blob/main/lib/ro.rb#L29-L55
 
-  ro.people.ara.related(:featured_posts)    
-    #=> all featured posts
-  
+because not having a repl sucks, so `ro` has one.  you should too.
+
+```sh
+
+# fire up the KONSOULLLLL!
+
+~> ro console ./public/ro/
 
 ```
 
-TRY
----
+```ruby
 
-```bash
+ro.posts.almost_died_in_an_ice_cave.attributes.keys #=>
 
-  ~ > git clone https://github.com/ahoward/ro.git
-  ~ > cd ro
-  ~> ./bin/ro console
+  ["og", "body", "assets", "_meta"]
 
+ro.posts.almost_died_in_an_ice_cave.attributes.og #=>
 
-  a:~/git/ahoward/ro $ ./bin/ro console
-  Ro(./ro):001:0> ro.people
-  => [people/ara, people/noah]
+  {"image"=>{"url"=>"/ro/posts/almost-died-in-an-ice-cave/assets/og.jpg"},
+   "title"=>"Almost Died In An Ice Cave",
+   "description"=>"On April of 2024, I, along with 6 of my friends, dug for our lives to come out on the other side."}
 
-  Ro(./ro):002:0> ro.people.ara
-  => people/ara
+ro.posts.almost_died_in_an_ice_cave.attributes.body.slice(0,420) #=>
 
-  Ro(./ro):003:0> ro.people.ara.first_name
-  => "Ara"
+  "<div class=\"ro markdown\">\n  <p><a href=\"#tl;dr;\">tl;dr;</a></p>\n\n<blockquote>\n  <p>in april, 2024, myself, and 6 brave men attempted to cross the harding\nicefield.</p>\n\n  <p>in celebration of <a href=\"https://en.wikipedia.org/wiki/Harding_Icefield#History\">yule kilcher’s 1968 crossing</a></p>\n\n  <p>midway through our trip, at the point of no return, we were beseiged by a storm of storms.</p>\n\n  <p>we dug shoulder to "
 
-  Ro(./ro):004:0> ro.people.ara.bio
-  => "<ul>\n<li>one</li>\n<li>two</li>\n<li>three</li>\n</ul>\n\n<p>pretty syntax highlighting</p>\n<div class=\"highlight\"><pre>  <span class=\"vi\">@a</span> <span class=\"o\">=</span> <span class=\"mi\">42</span>\n</pre></div>\n<p>Ara</p>\n\n<p>/ro/people/ara/assets/ara-glacier.jpg?_=1382999368</p>\n"
+ro.posts.almost_died_in_an_ice_cave.assets.first #=>
 
-  Ro(./ro):005:0> ro.people.ara.url_for('ara-glacier')
-  => "/ro/people/ara/assets/ara-glacier.jpg?_=1382999368"
+  "public/ro/posts/almost-died-in-an-ice-cave/assets/image1.png"
 
-  Ro(./ro):006:0> ro.people.ara.related
-  => [posts/hello-world, posts/second-awesome-post]
+ro.posts.almost_died_in_an_ice_cave.assets.first.url #=>
 
-  Ro(./ro):007:0> ro.people.ara.related.posts
-  => [posts/hello-world, posts/second-awesome-post]
+  "/ro/posts/almost-died-in-an-ice-cave/assets/image1.png"
 
-  Ro(./ro):008:0> ro.people.ara.related(:featured_posts)
-  => [posts/second-awesome-post]
 
 ```
 
-DESCRIPTION
------------
+__boom__ // **now we're cooking with gas!**
 
-ro is library for managing your site's content in git, as god intended.
+serveral things will be obvious to the non-ai enabled observer:
 
-it features:
+- every node has a hash of attributes
+- 'file' attributes are *rendered* based on file type
+- assets in rendered content are __url aware__
 
-- super fast loading via a robust caching/promise strategy
-- *all* teh templates supported via tilt (https://github.com/rtomayko/tilt)
-- the awesomest markdown ever, with syntax highlighting and even erb evaluation
-- an awesome command line tool for introspecting your data (./ro console)
-- data driven relationships
+you can see the list of file types `ro` supports here -> https://github.com/ahoward/ro/blob/main/lib/ro/template.rb#L43-L63
 
+if you can't build a website with just these...
 
-ro is the *perfect* companion to a site built by a static site generator such
-as middleman (http://middlemanapp.com/).  especially a middleman site with a
-companion rails' application doing concurrent modifications of the site's
-content... (ref: http://dojo4.com/blog/static-is-the-new-black) ;-)
+🙊 [you've come to the wrong place!](https://media0.giphy.com/media/v1.Y2lkPTc5MGI3NjExd2NpbmsxMHRxNnRsNjFzNWczN2JtejE5aXc0YXA3MHV3a3pwb3hodyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/vDlw1tKNwx40BGbWcQ/giphy.gif)
 
+---
+now, about that rendering process...
 
-INSTALL
--------
+for any 'html-ish' type, links to relative assets, will be expanded such that
+images will be resolved to thier final deployment destination.
 
-gem install ro
+eg. given __ro/posts/foo-bar/body.md__ containing the markdown
 
+```markdown
 
-CONFIG
-------
+[linky](./assets/report.pdf)
+
+![alty](./assets/pretty.png)
+
+```
+
+you will end up with html that looks like so:
+
+```html
+
+<a href='/ro/posts/foo-bar/assets/report.pdf'>linky</a>
+
+<img src='/ro/posts/foo-bar/assets/pretty.png'>alty</a>
+
+
+```
 
-if you are using the url methods you'll need to make sure your application can
-route to the assets.  by default ro assumes that the urls it generates are
-routeable under '/ro' so it is up to you to make sure this works.
+---
+__OH MAN THAT SUX I DO NOT WANT MY IMAGES STORED IN GH!!!!__
+
+*sit down... breathe...*
+
+and enable [git-lfs](https://git-lfs.com/)
+
+it used to be fragile but, since everyone the in the world is now checking in massive jupyter notebooks it 'just works'
+
+---
+now, recall what we said about `public` and `RO_URL`?  by default, this is is `/ro`...
+
+therefore, if we have:
 
-for a rails app this might mean writing a 'RoController' or, more simply, just
-putting your ro data in ./public/ro.
+`./public/ro/posts/foobar/...'
 
-for a middleman app this might mean putting your ro data in ./source/ro.
+paths found under `public` are going to start with `/ro`...
 
-if you choose a non-standard approach you'll need to
+> are you tracking yet?
 
+also, if you do not host your `ro` directory under public (but why not?  it
+*is* public content after all..), then you will need to set `RO_URL` to be the
+ultimate destination of your image deployment.  this can be cloudinary, s3,
+whatever.  it just needs to be the url prefix to whack in front of relative
+image urls.
+
+note - not only html has this 'expansion' applied, relative assets in your
+attributes will be expanded too, at any depth.  eg. -> https://github.com/ahoward/ro/blob/main/lib/ro/methods.rb#L233-L260
+
+this means code like this:
+
+```yaml
+# file: public/ro/posts/foo-bar/attributes.yml
+
+og:
+  image: ./assets/og.jpg
 ```
 
-  Ro.route = '/my-custom-route'
+will 'just work'. of course, this assumes that 'public/ro/foo-bar/assets/og.jpg' exists!
+
+the code is rather robust here, and is not a simple string bashing approach.
+
+it's tight, and you can trust it.
 
+---
+a bit about markdown...
+
+markdown is.  the web.  also AI, but i digress... if you aren't writing in
+markdown, you are probably writing `perl`... (nothing wrong with that btw!)
+
+but markdown has a lot of edge cases, not least of which syntax highlighting
+and bs css to deal with.
+
+`ro`, again, 'just works' here.
+
+- it uses github flavored markdown (gfm), extracts front-matter and folds it
+  into `attributes`, auto-links stuff (gfm does not), and inlines the css
+  styles for speed and so you don't have to eff with the css to render src
+  code all pretty.  see https://github.com/ahoward/ro/blob/main/lib/ro/template.rb#L117-L143
+
+- you can set the gfm theme via the `RO_MD_THEME` ENV var. this supports
+  anything [rouge](https://github.com/rouge-ruby/rouge) does.
+
+
+---
+> __I HATE RUBY!!!! RAWR__
+
+whatever.  use javascript.  `ro` is also a 'static cms api builder`.
+
+*WUT*?
+
+it can compile your entire content db into a static api of js, designed to be
+ultra, ultra, ultra easy to consume.  no stupid graphql thing, no bullsxxx
+api_key, no vendor lock-in to prismic, dato, contentful, or some other
+extorsionist regime., just a lil `fetch` and you are __GTG BRO!__
+
+you don't even have to render the stuff, it's pre-rendered html in the api ready to `dangerouslySetInnerHTM`!
+
+__(alsoCamelCaseMakeAPIHARDToReadWithEMPHASIS)__
+
+you can see an example here -> https://github.com/ahoward/ro/tree/main/public/api/ro
+
+i won't explain more now except to say that all you need to do to make a js
+bundle is
+
+```sh
+
+~> ro build
 
 ```
 
-in all cases ro urls will be prefixed by the route, so be sure that this prefix
-is either automatically, or manually, exposed.
+and then look carefully, it makes it easy to 'grab everything stupid style' or
+to paginate client side.  each collection has a `index.js` with everything, a
+`index-$pageno.js` with details about the next page, iff any, and of course, it
+produces an `index.json` file, complete with those gnarly *width* and *height*
+numbers you need to *fight FUOC* and layout shift.
+
+if you don't know what that means, probably use [wordpress](https://drawohara.io/dojo4/archive/irish-dance-and-wordpress-the-soul-destroyer/)
+
+lil detail about that link^, it is from *10 years ago*, when dojo4 was still running, and running on `ro`.
+
+---
+
+one super comman pattern, is to add a build step to a github workflow, and
+then publish the js api via gh-pages. see an example here:
+
+https://github.com/ahoward/ro/blob/main/.github/workflows/gh-pages.yml
+
+__WUT!?!?!___
+
+- your content is in github
+- you want to consume it in js
+- add a build step to build the js api and deploy it via gh-pages
+- consume that 'static cms api' via fetch
 
+*free*, image ready, headless CMS.  yep.
+
+... 🤯🤯🤯
+
+---
+
+finally, and, truly, this is possibly the *coup de grâce*, you can just
+friggin use github as your CMS now!  why?  because the markdown previw on
+gh... just works. 🤤
+
+eg.  https://github.com/ahoward/ro/blob/main/public/ro/posts/almost-died-in-an-ice-cave/body.md
+
+ADVANCED
+---------
+
+- include the public directory in your gh-pages, pull that shit through
+  cloudinary/imgix/etc as the img src... responsive images, with client side
+  processing.  zero work.
+
+- use ro in your rails app/models with the `active_model` adapter.
+  https://github.com/ahoward/ro/blob/main/lib/ro/model.rb , it supports
+  pagination and all the things.  rails ready.
+
+- explore built-in support for syntax highlighted source code.  just put a
+  file in ./assets/src/a.rb and it 'just works'
+
+- explore the api in the repl, you'll find POLS stuff like
+
+```ruby
+
+  ro.get('posts').get('almost-died-in-an-ice-cave')
+
+  ro.get('posts/almost-died-in-an-ice-cave')
+
+  ro.get('posts').get('almost-died-in-an-ice-cave').assets.first.img
+
+  #=> {:format=>"png", :width=>1456, :height=>817}
+
+```
 
 DOCS
 ----
+1) vibe it AI
+2) RTFC
+
+BORING SHIT
+-----------
+
+```sh
+
+  ~> gem install ro
+
+```
+
+LICENSE
+-------
+https://github.com/LGUG2Z/komorebi-license
 
-RTFC
+AI
+--
+suck it 🤖s!