[ruby-talk:444652] [ANN ro-v4.4.0]

a11 · 23 April 2025 08:15

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*.

---

to grok `ro` it is best to start with an example of some real content,
for a real site.

cf2ba9b97edadcd224c137ae195880dc

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.

- the essential layout is

9bd6db4232a24bec5a8bfe533e49f1db

if you learn best by example, you can examine the `ro` directory of my own
website here -> drawohara.io/public/ro at main · ahoward/drawohara.io · GitHub

- several environment variables control how `ro` works, most notably

53ca0e29703a7c3fbc23644afb291080

more about this can be rtfm'd here ->

github.com/ahoward/ro

lib/ro.rb

main


      
          def env
            Map.for({
              :root      => ENV['RO_ROOT'],
              :build     => ENV['RO_BUILD'],
              :url       => ENV['RO_URL'],
              :img_url   => ENV['RO_IMG_URL'],
              :page_size => ENV['RO_PAGE_SIZE'],
              :log       => ENV['RO_LOG'],
              :debug     => ENV['RO_DEBUG'],
              :port      => ENV['RO_PORT'],
              :md_theme  => ENV['RO_MD_THEME'],
            })
          end
          
          def defaults
            Map.for({
              :root      => './public/ro',
              :build     => './public/api/ro',
              :url       => "/ro",
              :img_url   => "/ro",

This file has been truncated. show original

because not having a repl sucks, so `ro` has one. you should too.

11f45ed7e1b6d15e5dc82107dbefc599

4be7223936052fa04e59ce812696416d

__boom__ // **now we're cooking with gas!**

serveral things will be obvious to the non-ai enabled observer:

- 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 ->

github.com/ahoward/ro

lib/ro/template.rb

main


      
          content =
            case engine
              when 'html'
                render_html(content)
              when 'txt', 'text'
                render_text(content)
              when 'erb'
                render_erb(content, context:)
              when 'md', 'markdown'
                render_markdown(content)
              when 'yml', 'yaml'
                render_yaml(content)
              when 'json'
                render_json(content)
              when 'rb'
                render_ruby(content)
              when 'txt', 'text'
                render_text(content)
              else
                Ro.error!("no engine found for engine=#{ engine.inspect } engines=#{ engines.inspect }")
            end

if you can't build a website with just these...

[you've come to the wrong place!](
giphy
)

---
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

6a4f6131089c04aa739a77fa72d6f8bd

you will end up with html that looks like so:

e3fa3f55750671c03a660f84580e351b

---
__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:

`./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. ->

github.com/ahoward/ro

lib/ro/methods.rb

main


      
          def expand_asset_values(hash, node)
             src = Map.for(hash)
             dst = Map.new(hash)
          
             return dst if src.empty?
          
             re = %r{\A(?:[.]/)?(assets/[^\s]+)\s*\z}
          
             src.depth_first_each do |key, value|
               next unless value.is_a?(String)
          
               if (match = re.match(value.strip))
                 path = match[1].strip
                 url = node.url_for(path)
                 value = url
               end
          
               dst.set(key, value)
             end

This file has been truncated. show original

this means code like this:

f094470280d19a54ffaec199cd75a2be

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

github.com/ahoward/ro

lib/ro/template.rb

main


      
          def Template.render_markdown(content, options = {})
            content = String(content).force_encoding('utf-8')
            options = Map.for(options.is_a?(Hash) ? options : { context: options })
          
            theme = options.fetch(:theme) { Ro.config.md_theme }
          
            parsed = FrontMatterParser::Parser.new(:md).call(content)
            front_matter = parsed.front_matter
            content = parsed.content
          
            opts = {
              input: 'GFM',
              hard_wrap: false,
              syntax_highlighter_opts: { formatter: RougeFormatter, theme: theme }
            }
          
            div =
              <<~_____
                <div class="ro markdown">
                  #{ ::Kramdown::Document.new(content, opts).to_html }

This file has been truncated. show original

- you can set the gfm theme via the `RO_MD_THEME` ENV var. this supports
anything [rouge](GitHub - rouge-ruby/rouge: A pure Ruby code highlighter that is compatible with Pygments) 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 ->

i won't explain more now except to say that all you need to do to make a js
bundle is

fec83b7b4c42593fb47bbab8206b70e7

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](

)

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:

github.com/ahoward/ro

.github/workflows/gh-pages.yml

main

# 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:

This file has been truncated. show original

__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.

github.com/ahoward/ro

public/ro/posts/almost-died-in-an-ice-cave/body.md

main

[tl;dr;](#tl;dr;)

> in april, 2024, myself, and 6 brave men attempted to cross the harding
> icefield.
>
> in celebration of [yule kilcher's 1968 crossing](https://en.wikipedia.org/wiki/Harding_Icefield#History)
>
> midway through our trip, at the point of no return, we were beseiged by a storm of storms.
>
> we dug shoulder to shoulder for 5 days before the air national gaurd crash
> landed, and we crawled into the void on a one way journey to save each other's
> lives at a bearing of 300, 900 meters away.
>
> these are my memories from that trip.
>
> they are not meant to be definiative or complete; merely a refelection on how
> the experience sits in my mind.
>
> it took me a full year to be able to put pen to paper about this so, forgive
> any tresspasses.

This file has been truncated. show original

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.
ro/lib/ro/model.rb at main · ahoward/ro · GitHub , 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

89687ae71d531a37365426f4d9501ade

DOCS
----
1) vibe it AI
2) RTFC

BORING SHIT
-----------

cdd246c3d740cf39bd5a182a250c410e

LICENSE
-------

AI
--
suck it s!

enjoy. peace!

--
- a
"be kind whenever possible. it is always possible." -- h.h. the 14th
dalai lama
-->> https://drawohara.io

Topic		Replies	Views
Re: [Ruby] No more html ruby-talk	4	495	6 February 2018
Newbie questions ruby-talk	1	63	16 December 2003
CMS in ruby ruby-talk	5	76	26 January 2005
RDoc, YARD, TomDoc or? ruby-talk	1	152	9 August 2011
Open source project needs help ruby-talk	3	113	17 November 2006

Related topics