Haskell static site generator based on Shake (superseded by https://github.com/srid/ema)
Home Page: https://rib.srid.ca
License: BSD 3-Clause "New" or "Revised" License
Rib is a Haskell static site generator based on Shake, with a delightful workflow.
See https://rib.srid.ca for full documentation.
UPDATE (Apr, 2021): Rib is superceded by Ema
Use ghcid for quicker compilation cycles:
nix-shell --run "cd rib-core && ghcid"To test your changes, clone rib-sample and run it using your local rib checkout:
cd ..
git clone https://github.com/srid/rib-sample.git
cd rib-sample
nix-shell --arg rib ../rib --run 'ghcid -T ":main -wS"'
To fix it, make readSource set a custom source URL.
More generally, perhaps sourceUrl should not be computed automatically especially as the target HTML path can be changed by the user.
For example, using netlify and Github Actions. cf. open-editions/open-editions.org#6 (comment)
Currently WIP at rib.srid.ca
Rib.Shake combinators (explain using Rib.Simple)Rib.Pandoc functionsisDraftAs i am doing some developing, it would be handy to have.
For now, I just made an orphan instance to use while developing.
One thing I want to solve is the structure of the generated URLs: I'd like the final HTMLs to be accessible as example.com/yyyy/mm/dd/my-great-post. This is to keep the old URLs working after the migration. I have some ideas, but it's not working yet.
Currently rib does not have any blogging-specific functionality. If rib is to gain such explicit capabilities (be it as a built-in feature or as an extension), what is the list of things it should support? Here's a tentative list, for initial brainstorming:
This would be same as Rib.Simple except, the URLs would end in .html - unless the generation happens in a directory-per-page level (eg: ./foo/index.html for every foo.md).
From @rkaippully
- Is nix required? The doc is worded to suggest that way, but I suspect it’s not mandatory. There are a lot of haskellers that do not use nix, so this might be a barrier to entry.
Allow content and its metadata to be specified in Dhall configuration language.
Add a new source parser that does this, while making sure that a predefined subset of the Dhall field is parsed using existing LML parser (eg: mmark).
For optional access to relude.
Some ideas here:
https://svejcar.dev/posts/2019/11/27/table-of-contents-in-hakyll/
From @ChrisPenner
I don't see any links to the hackage docs, nor could I find it on hackage; if I can't see hackage docs then using a package is basically a no-go for me 😬; my advice would be to focus your documentation around existing flows; put your getting started tutorial directly in the readme so it's copied to your hackage packages front page. Best to use the "de-facto" patterns for docs for at least the "first glance" stuff or the barrier to entry gets too high IMHO
And then [ ] upload to hackage.
Rib should lock the directory when watching for changes, so that a second instance is prohibited at the beginning.
This should behave similar to Shake's locking, which reports as follows (when two instances of rib process is running at the same time, and a source file gets changed):
[Rib] Watching a/ for changes
# a/tidbits.dhall
[Rib] Shake error: Shake failed to acquire a file lock on .shake/.shake.lock
Shake process ID 30041 is using this lock.
setLock: resource exhausted (Resource temporarily unavailable)
CallStack (from HasCallStack):
errorIO, called at src/General/FileLock.hs:67:9 in shake-0.18.4-5VRu9yKqXOY
JrfQmbOPO6w:General.FileLock
Different target directories use the same Shake cache.
Errors from parsing of markup and its metadata are thrown as exceptions (using fail), and Shake presents them with the traceback as follows:
We should present a nicer error message instead, possibly in a single line.
Provide reflex-dom as an alternative renderer to Lucid.
Pandoc and MMark renderer should support reflex-dom (including syntax highlighting). They can do it via lucid, by converting the resulting HTML into reflex-dom nodes.
If I move /notes/foo.html to /blog/2020/foo.html, I'd like the former location to redirect to the newer one.
Since this is a static site with no dynamic server, we would implement this using the http-equiv="Refresh" property of the meta tag in HTML. And as long as delay is zero, search engines will update their index.
This may not even need code change, and could simply be documented with example under FAQ.
It should show only the core features. For advanced features like routes and dhall, link to Main.hs.
[@joelmccracken has expressed interest in working on this]
Currently to add a custom markup, the user will have to do two things:
IsMarkup type class instance for their markup doc typeMarkup doc type to add a constructor corresponding to their markupStep 2 in particular involves forking and modifying rib. We should aim to avoid that.
One way is perhaps to make buildHtmlMulti work on the IsMarkup constraint, and have the user explicit specify the markup type using TypeApplication.
cf. zulip-archive for an example
Add a function that returns a tree of section headers that user's Main.hs can use to render a personalized table of contents.
Use src and dest as default.
Rib.App overridable by the user.Rib.Shake.Suggested by @joelmccracken
I personally am not a fan of it, but some users seem to feel strongly about needing to use specific names for directories. I will accept changes that does not complicate the current implementation.
Pandoc's org-mode parser is very limited. Alternatively we can extract the structure of the document as JSON using elisp: https://github.com/ludios/org-to-json and then convert the JSON to HTML.
Requires emacs with org-mode installed.
Primary tasks:
org-to-json spits out.Make a newtype wrapper, and then provide instances.
Like parse but takes a custom list of mmark extensions to use.
Also add parsePureWith.
Use an unique theme for rib.srid.ca. Don't overuse semantic-ui segments.
https://www.reddit.com/r/haskell/comments/eqc698/ann_reflexghci_a_ghcidlike_program_for/
Not totally convinced yet, but a path worth exploring ... especially as obelisk will be migrating as well. Could even use the underlying reflex-vty to do stuff like creating a sub-command that shows the user a CLI wizard for create new file/ item/ blog post (or even modify it).
AsciiDoc seems like a fantastic markup language that is more feature-rich than Markdown whilst remaining simpler than XML.
No complete Haskell parser seems to exist for it, so we may have to shell out to asciidoctor.
At minimum, have writeFileCached return the last modified time of the file.
With shakeTimings = True:
Function shake 0.000s 0%
Database read 0.894s 73% =========================
With database 0.072s 5% ==
Running rules 0.246s 20% ======
Pool finished (1 threads, 1 max) 0.000s 0%
Cleanup 0.000s 0%
Total 1.212s 100%
Size of the database for this report:
$ du -sh .shake/
28M .shake/
$
When the Haskell file is changed, this can occur just before ghcid has the chance to reload:
Error when reading Shake database .shake/.shake.database
AsyncCancelled
All files will be rebuilt
An otherwise "static" site might gain from being parts of the site being a bit dynamic.
For example, using highlight.js to highlight syntax on the fly. Or do some custom JS eval on the page.
Rib already allows the use of Haskell DSL to define the HTML and CSS of the site. It could do the same for JavaScript as well, through GHCJS.
And it might be worth considering replacing Lucid with (or adding support for) Reflex-DOM, and use the reflex library to implement this feature.
I was hoping that the directory structure of the source area would be replicated in the target, that is, a/some/path/index.md would end up at b/some/path/index.html. Is there a way to get this to work that I'm missing?
Thanks! Great static site generator, by the way.
Allow users to add custom subcommands to the built executable.
We currently only support a small subset of Pandoc reader formats. This is specified in the Rib.Markup.Pandoc.detectReader function.
We should ideally make use of the Text.Pandoc.Readers.readers list, but filtering only for readers of type TextReader. We would also need a map between readers and their file extensions.
source-overrides is supported, but that can only override the source and not the derivation itself.
And remove this from the Haddock of run:
NOTE: This should ideally not be
"."as our use of watchTree (of runWith) can interfere with Shake's file scaning.
Explore if it is beneficial replacing path with hpath,
https://github.com/hasufell/hpath
Seeing a lot of these if the source files updated very frequently.
[Rib] Shake error: .shake/.shake.database: openFile: resource busy (file is locked)
Viz.:
[Rib] Serving at http://localhost:8080
# a/static/README.md
# a/2019/12/26.md
*** Exception: Error when running Shake build system:
at action, called at src/Development/Shake/Forward.hs:111:5 in shak
e-0.18.3-94gZtzt3YtDAYX9Ox6TYrO:Development.Shake.Forward
* Raised the exception:
b/2019/12/26.html: openFile: does not exist (No such file or directory)
To be spec'ed out.
For references, see
buildHtmlMulti #77 (comment)To reproduce, add draft: True (without double quotes around the True) to metadata of a document. Expect to see either nothing or this:
Subsequent save of file (after fixing it) has no effect.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.