ro 4.2.0 → 5.0.0

data/README.md

@@ -1,178 +1,353 @@
-NAME
-====
+TL;DR:
+------
 
-`ro`
+`ro` stands for `read only`, and it is the tiniest, best, headless cms.
 
-INSTALL
-=======
+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 separate 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*.
+
+---
+
+to grok `ro` it is best to start with an example of some real content,
+for a real site.
 
-as a gem
 
 ```sh
-  ~> gem install ro
+
+  drawohara@drawohara.dev:ro[main] #=> tree public/ro/posts/almost-died-in-an-ice-cave/
+  public/ro/posts/
+  ├── almost-died-in-an-ice-cave.yml    # ← metadata file at collection level
+  └── almost-died-in-an-ice-cave/       # ← node directory
+      ├── assets/                        # ← assets subdirectory
+      │   ├── image1.png
+      │   ├── image2.png
+      │   ├── image3.png
+      │   ├── og.jpg
+      │   └── purple-heart.jpg
+      └── body.md                        # ← other content files
+
 ```
 
+in this example you can see a few things, regarding the layout of a `ro` directory:
+
+- `ro` content often, but is not required, to live in `public`.  more on this below.
 
-SYNOPSIS
-========
+- the essential layout is (v5.0+):
 
-keep all your content in git as god intended.
+```ruby
 
-even images.
+    @root       = "ro"
+    @collection = "posts"
+    @id         = "almost-died-in-an-ice-cave"
 
-fuck wordpress.
+    # metadata file
+    "#{ @root }/#{ @collection }/#{ @id }.yml"
 
-# TL;DR;
+    # node directory
+    "#{ @root }/#{ @collection }/#{ @id }/"
 
-`ro` is the world's tiniest, simplest, zero-config, and most bestest headless CMS.
+    # assets
+    "#{ @root }/#{ @collection }/#{ @id }/assets/"
 
-it keeps your content in an on disk bundle that will make sense to an 11 year
+```
 
-it depends on nothing but GitHub itself for the storage, management, and
-delivery of rich web content and assets.
+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
 
-## Storage
+- several environment variables control how `ro` works, most notably
 
-`ro` keeps your structured web content in a super sane structure, that keeps
-assets close to its related content, allows for structured data to be kept
-along side markdown/html content, and which supports source code as a first
-class citizen.
+```ruby
 
-For example, given:
+  # this is the fs root of all ro content
+  #
+
+  Ro.root = ENV['RO_ROOT'] || './public/ro'
+
+  # this is the url where ro content, especially images, will be expected to
+  # live at when live
+
+  Ro.url = ENV['RO_URL'] || '/ro'
 
-```sh
-    ~> tree ro/data
-
-    # ro/data
-    # └── posts
-    #     ├── first-post
-    #     │   ├── attributes.yml
-    #     │   └── body.md
-    #     │   ├── blurb.erb.md
-    #     │   ├── assets
-    #     │   │   ├── foo.jpg
 ```
 
-`ro` will provide an interface logically consistent with:
+more about this can be rtfm'd here -> https://github.com/ahoward/ro/blob/main/lib/ro.rb#L29-L55
+
+because not having a repl sucks, `ro` has one.  you should too.
+
+```sh
+
+# fire up the KONSOULLLLL!
+
+~> ro console ./public/ro/
+
+```
 
 ```ruby
-    node.attributes        #=> any/all the data loaded from 'attributes.yml'
-    node.attributes.body   #=> an HTML representation of 'body.md' 
-    node.attributes.blurb  #=> an HTML representation of 'blurb.md' 
-    node.attributes.assets #=> list of assets with url and path info
+
+ro.posts.almost_died_in_an_ice_cave.attributes.keys #=>
+
+  ["og", "body", "assets", "_meta"]
+
+ro.posts.almost_died_in_an_ice_cave.attributes.og #=>
+
+  {"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.posts.almost_died_in_an_ice_cave.attributes.body.slice(0,420) #=>
+
+  "<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.posts.almost_died_in_an_ice_cave.assets.first #=>
+
+  "public/ro/posts/almost-died-in-an-ice-cave/assets/image1.png"
+
+ro.posts.almost_died_in_an_ice_cave.assets.first.url #=>
+
+  "/ro/posts/almost-died-in-an-ice-cave/assets/image1.png"
+
+
 ```
 
-To learn more, clone this repo, `bundle install`, and fire up a console to
-check play with this idea:
+__boom__ // **now we're cooking with gas!**
 
-eg: [given this node](https://github.com/ahoward/ro/tree/main/ro/data/posts/first-post)
+serveral things will be obvious to the non-ai enabled observer:
 
-```ruby
-    ~> ro console
+- every node has a hash of attributes
+- 'file' attributes are *rendered* based on file type
+- assets in rendered content are __url aware__
+
+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...
+
+🙊 [you've come to the wrong place!](https://media0.giphy.com/media/v1.Y2lkPTc5MGI3NjExd2NpbmsxMHRxNnRsNjFzNWczN2JtejE5aXc0YXA3MHV3a3pwb3hodyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/vDlw1tKNwx40BGbWcQ/giphy.gif)
+
+---
+now, about that rendering process...
+
+for any 'html-ish' type, links to relative assets, will be expanded such that
+images will be resolved to thier final deployment destination.
+
+eg. given __ro/posts/foo-bar/body.md__ containing the markdown
+
+```markdown
 
-    ro[./ro/data]:001:0> ro.posts.first_post.title
-    => "First Post"
+[linky](./assets/report.pdf)
 
-    ro[./ro/data]:002:0> ro.collections.posts.first_post.assets.first.url
-    => "/ro/posts/first-post/assets/foo.jpg"
+![alty](./assets/pretty.png)
 
-    ro[./ro/data]:003:0> ro.collections.posts.first_post.body.slice(0,42)
-    => "<div class='ro markdown'>\n  <ul>\n  <li>one"
 ```
 
+you will end up with html that looks like so:
 
-## Management
+```html
 
-Managing `ro` is as simple as using the built-in GitHub Markdown editor.  The
-file system layout, which supports relative asset urls, means the built-in
-editor preview renders just fine.  Of course, you are free to manage content
-programatically as well.  Either way, updates to the the content will result
-in an automated API build of a static API which is then deployed to GitHub
-Pages.
+<a href='/ro/posts/foo-bar/assets/report.pdf'>linky</a>
 
-This is made possible by certain design decisions `ro` has made, specifically
-allowing assets/ to be stored and rendered relative to their parent content.
+<img src='/ro/posts/foo-bar/assets/pretty.png' alt='alty'>
 
-Of course, you have all the power of `git` so other methods of managing the
-content are available, programtic, locally in vs-code, etc.  You have lots of
-simply options, none of which require drivers or databases, and all of which
-provide perfect history over your valuable web content and assets.
 
-A word on managing assets, if you plan to have many large images, you probably
-want to enable GitLFS on your content repository, `ro` plays perfectly with
-it.
+```
 
+---
+__OH MAN THAT SUX I DO NOT WANT MY IMAGES STORED IN GH!!!!__
 
-## Delivery
+*sit down... breathe...*
 
-Delivery of `ro` content, to remote clients, is via http+json.  To output your
-content as json, you simply need to run
+and enable [git-lfs](https://git-lfs.com/)
 
-```sh
-    ~>  ro build
-
-		ro.build: public/ro -> public/api/ro
-		ro.build: public/api/ro/posts/first_post/index.json
-		ro.build: public/api/ro/posts/second_post/index.json
-		ro.build: public/api/ro/posts/third_post/index.json
-		ro.build: public/api/ro/posts/index/0.json
-		ro.build: public/api/ro/posts/index.json
-		ro.build: public/api/ro/index/0.json
-		ro.build: public/api/ro/index.json
-		ro.build: public/api/ro/index.html
-		ro.build: public/ro -> public/api/ro in 0.08s
+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:
+
+`./public/ro/posts/foobar/...'
+
+paths found under `public` are going to start with `/ro`...
 
+> 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.yml
+
+og:
+  image: ./assets/og.jpg
 ```
 
-During the build, assets are expanded to be the full URL of the final
-deployment destination.  This is done via the RO_URL environment variable, and
-automatically with a pre-build GitHub Action that will deploy your content via
-GitHub Pages. See
-https://github.com/ahoward/ro/blob/main/.github/workflows/gh-pages.yml#L55 for
-more details.
+will 'just work'. of course, this assumes that 'public/ro/posts/foo-bar/assets/og.jpg' exists!
+
+the code is rather robust here, and is not a simple string bashing approach.
 
-You can view sample output from this Action, deployed to GH Pages here: https://ahoward.github.io/ro
+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!)
 
-# USAGE
+but markdown has a lot of edge cases, not least of which syntax highlighting
+and bs css to deal with.
 
-#### WRITE-ME // #TODO
+`ro`, again, 'just works' here.
 
-## API // Javascript
+- 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
 
-#### WRITE-ME // #TODO
+- you can set the gfm theme via the `RO_MD_THEME` ENV var. this supports
+  anything [rouge](https://github.com/rouge-ruby/rouge) does.
 
-## CLI
 
-#### WRITE-ME // #TODO
+---
+> __I HATE RUBY!!!! RAWR__
 
-## Programatic // Ruby
+whatever.  use javascript.  `ro` is also a 'static cms api builder`.
 
-#### WRITE-ME // #TODO
+*WUT*?
 
-## Via Repository
+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!__
 
-#### WRITE-ME // #TODO
+you don't even have to render the stuff, it's pre-rendered html in the api ready to `dangerouslySetInnerHTM`!
 
-- note on http vs https
+__(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
 
-SAMPLES
-=======
-  #### <========< [samples/a.rb](https://github.com/ahoward/ro/blob/main/samples/a.rb) >========>
 ```sh
-  ~ > cat samples/a.rb
+
+~> ro build
+
 ```
+
+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 common 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
-    require 'ro'
-    
-    p 42
+
+  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
-  ~ > ruby samples/a.rb
-```
-```txt
-    42
+
+  ~> gem install ro
+
 ```
 
+LICENSE
+-------
+https://github.com/LGUG2Z/komorebi-license
+
+AI
+--
+suck it 🤖s!
+
+REF
+---
+https://github.com/ahoward/ro

data/Rakefile

@@ -312,8 +312,8 @@ BEGIN {
   This.version      = This.object.version
   This.dependencies = This.object.dependencies
   This.summary      = This.object.summary
-  This.description  = This.respond_to?(:description) ? This.description : This.summary
-  This.license      = This.respond_to?(:license) ? This.license : IO.binread('LICENSE').strip
+  This.description  = This.object.respond_to?(:description) ? This.object.description : This.summary
+  This.license      = This.object.respond_to?(:license) ? This.object.license : IO.binread('LICENSE').strip
 
 # discover full path to this ruby executable
 #

data/a.yml

@@ -0,0 +1,60 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: deploy ro content, api, and site to gh-pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        # NOTE: this enables git-lfs and caching
+        # - https://github.com/actions/checkout/issues/834
+        # - https://github.com/nschloe/action-cached-lfs-checkout
+        uses: nschloe/action-cached-lfs-checkout@v1
+        # you may use this instead, if you don't want git-lfs caching
+        #uses: actions/checkout@v4
+        #with:
+        #   lfs: true
+      - name: setup gh-pages
+        uses: actions/configure-pages@v3
+        id: gh-pages
+      - name: ro build
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - run: |
+            export RO_URL=${{ steps.gh-pages.outputs.base_url }}/ro
+            export RO_PAGE_SIZE=2
+            bundle exec ./bin/ro build ./public/ro ./public/api/ro
+            bundle exec ro site public
+            tree ./public
+      - name: upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: "./public"
+      - name: deploy gh-pages
+        id: deployment
+        uses: actions/deploy-pages@v2

data/bin/ro

@@ -130,6 +130,10 @@ Ro.script do
     site!
   end
 
+  run(:migrate) do
+    migrate!
+  end
+
   def setup!(*which)
     setup_env!
 
@@ -259,6 +263,12 @@ Ro.script do
     index_html.binwrite(html)
     puts index_html
   end
+
+  def migrate!
+    require "#{$libdir}/ro/script/migrate.rb"
+
+    Ro::Script::Migrate.run!(script: self)
+  end
 end
 
 BEGIN {

data/lib/ro/_lib.rb

@@ -1,5 +1,5 @@
 module Ro
-  VERSION = '4.2.0' unless defined?(VERSION)
+  VERSION = '5.0.0' unless defined?(VERSION)
 
   class << self
     def version
@@ -28,7 +28,7 @@ module Ro
 
     def libs
       %w[
-        fileutils pathname yaml json logger erb cgi rexml time date thread
+        fileutils pathname yaml json logger erb cgi uri time date thread securerandom
       ]
     end
 
@@ -46,11 +46,23 @@ module Ro
         'rouge' =>
           ['rouge', '~> 4.1', ' >= 4.1.1'],
 
-        'ak47' =>
-          ['ak47', '~> 0.2'],
+        'front_matter_parser' =>
+          ['front_matter_parser', '~> 1.0'],
 
-        'webrick' =>
-          ['webrick', '~> 1.8.1'],
+        'rinku' =>
+          ['rinku', '~> 2.0'],
+
+        #'ak47' =>
+          #['ak47', '~> 0.2'],
+
+        #'webrick' =>
+          #['webrick', '~> 1.9.1'],
+
+        'image_size' =>
+          ['image_size', '~> 3.4'],
+
+        'nokogiri' =>
+          ['nokogiri', '~> 1'],
       }
     end