Reducing boilerplate

[ispringle]

I'm wondering what it would take to reduce the boiler plate needed to get uniorg working in a project. Likely it'd be some sort of separate project or module because the boilerplate is going to be somewhat specific to the framework being used.

[rasendubi]

Hey. What kind of boilerplate do you mean? Uniorg has some examples for basic parsing and a Next.js-based blog.

[ispringle]

Yes, I have that all setup and mostly working (refactoring, not sure if the master branch on my project works atm). My project is here: https://github.com/pard68/sylvan

My idea was to take those examples and then create modules from them. They would of course be opinionated, and people would have the option not to use them, but it would make for a simpler setup for people. Instead of everyone having roughly the same code in src/lib you could add a module for your specific framework, say uniorg-next. You would give it the directory to of org files to process, you could override/update the pipeline, but would be otherwise stock parts.

My thought was making basic usage something along the lines of:

[...slug].js

import uniorgInit from 'uniorg-next';

const [ getAllPaths, getAllPosts, getPostBySlug ] = uniorgInit({ pagesDirectory = 'public/' });
...

For people who just want to have some basic orgfile processing and maybe some rehype stuff done, this would eliminate the need for the lib/ dir and the various files that need to be in there (or w/e you put it). For more advanced file processing, you could make the AST generation somewhat configurable and then for the rehype processing you could actually just accept a function that is a chain of rehype modules.

[rasendubi]

It's hard to create a common plugin for Next.js because some aspects are still hacky or differ between setups (e.g., copying referenced images to output, or resolving cite links).

I was researching this topic and Gatsby seems to be a better fit for a common base (because it has a proper processing pipeline and caching). I even experimented with a uniorg plugin for Gatsby at some point but I didn't drive it to completion. Maybe I should try again

[ispringle]

I am unfamiliar with Gatsby, but it might be a good starting place. Based on using plugins like Contentlayer, Orgjs, and others, I think it's possible to do something for NextJS as well, though with the caveat that if you want something terribly advanced, such as maybe some of the things in your own site's pipeline, you might need to implement your own tooling. But, I think it'd probably cover the bases for 70% of people and that would make this a lot more approachable for people on the Orgjs project (which appears to be possibly abandonware at this point).

[rasendubi]

UPD: I am currently experimenting with Astro and published an astro-org integration that allows importing .org files in JS/Astro. It can be used as follows.

In astro.config.mjs:

import org from 'astro-org';

export default defineConfig({
  ...
  integrations: [ org({}) ],
};

Then in pages/[...slug].astro:

---
export async function getStaticPaths() {
  const posts = await Astro.glob('../org/**/*.org');
  return posts.map(post => ({
    params: {
      slug: ...get slug from post...
    },
    props: post,
  }));
}

const { default: Content, frontmatter, file } = Astro.props;
---

<h1>{frontmatter.title}</h1>
<Content />

This is still pretty much bare-bones and I have more features implemented on my website: resolving id: and cite: links, working with bibtex files, processing images, and more.

Though, it might serve as a good starting point—having a list of all org posts is enough to enable other features (id:, cite:, and file: links resolution, optimizing images, hiding drafts, etc.). It should be possible to build API similar to Astro collections

Something along the lines of:

const collection = defineOrgCollection({
  entries: import.meta.glob('../org/**/*.org', { eager: true }),
});

const entry = collection.getEntryBySlug('post-1');

Maybe we can even integrate this into Astro, so it becomes a normal Astro collection

[ispringle]

I moved to Astro in October of last year. I had a pretty janky uniorg integration working but yours is vastly superior. I can't figure out the vite/rollup stuff at all, so I am glad to see you discovered Astro as well. I've started using astro-org and it's great and more or less what I was getting at with this. Gonna close this now.