SSG

[Malix-Labs]

Hello again !

I think it would be a nice thing to publish your project with an SSG (typically GitHub Pages)

[omarbassam88]

This is indeed the plan. The simplest solution that I have in mind now is to make a Makefile that exports all the README.org files to index.html. Maybe in the future we can move to a more robust scriptable solution like org-publish to include better styling or add search funcionality. Let me know if you have better solutions or suggestions.

[Malix-Labs]

I think only markdown is supported by Jerkyll

If you don't want to convert .org to .md, a .org preprocessor would be needed, indeed

Related

• https://orgmode.org/manual/HTML-Export.html
• https://orgmode.org/worg/org-tutorials/org-jekyll.html
• https://emacs.cc/jekyll-org/
• https://ox-hugo.scripter.co/

[omarbassam88]

Well there's also an option to use Hugo with org-mode

https://ox-hugo.scripter.co/

[omarbassam88]

BTW I already bought the domain lisp-spectrum.org

[Malix-Labs]

BTW I already bought the domain lisp-spectrum.org

Nice thing

Custom domains also works with GitHub pages

[Malix-Labs]

Or just simply use https://orgmode.org/manual/HTML-Export.html

I guess it would not be that hard to use it in a GitHub action

[omarbassam88]

Yes, this should be pretty simple. We just need to decide on the static site generator first.

[Malix-Labs]

Maybe just Static HTML by GitHub Actions (you can found it in GitHub Pages)

[omarbassam88]

I believe we basically need a static site generator that allows us to:

• support org mode.
• allow to add custom styling.
• allow to rename exported files.

[Malix-Labs]

Yeah

Jekyll is only WEB (HTML, CSS, JS) + markdown

the static HTML by GitHub action only works with HTML, so it would work but would require a preprocessing build step

In that case, I guess https://orgmode.org/manual/HTML-Export.html would be the most straightforward and extensible preprocessing build step

[omarbassam88]

Yes, we can write an emacs script that builds the whole website from the org files, rename the README ones to index and maybe insect a styling css file.

Would you be liek to work on that together?

[Malix-Labs]

To be really honest, I did not know about .org before lol, but I'm willing to try to implement a GitHub Action preprocessor for .org files (perhaps using orgmode.org/manual/HTML-Export.html)

[omarbassam88]

You don't need to know org-mode. If you just know some emacs lisp you can write a script, for example build.el that scans the folder for all .org files and export them, change their name from README.html to index.html.

We will also need a step to replace all links that refer to README.org with the equivalent index.html. currently, there's no document that is linking to the other ones. But definetly in the future there will be.

[omarbassam88]

You can run emacs-lisp script using the command emacs --script. Emacs is a lisp interpreter after all.

[omarbassam88]

https://www.youtube.com/watch?v=AfkrzFodoNw&t=13s

[Malix-Labs]

If you just know some emacs lisp

Also no, I only know some GNU Guix's Guile Scheme

[Malix-Labs]

content of the video above in text : https://systemcrafters.net/publishing-websites-with-org-mode/

[Malix-Labs]

https://orgmode.org/manual/HTML-export-commands.html

I think that is sufficient, right ?

[omarbassam88]

It can be sufficient for now. However, it will need more processing in the future to handle renaming of the files and fixing broken links.

I think we can use org-publish which will be a more ready (and customizeable solution for our needs.

Check this tutorial as a good example of what we are trying to achieve.

[Malix-Labs]

It can be sufficient for now. However, it will need more processing in the future to handle renaming of the files and fixing broken links.

Wouldn't links also be converted to HTML's href ?

[Malix-Labs]

Oh, I didn't noticed org-publish was different than export

[Malix-Labs]

https://github.com/marketplace?query=org+publish

Found that :

• org
  • https://github.com/marketplace/actions/org-publish
• org-roam
  • https://github.com/marketplace/actions/org-roam-publish
  • https://github.com/marketplace/actions/publish-org-roam-ui

Are you using org or org-roam ?

I do not know any single thing about any

[omarbassam88]

I managed to write the basic script:

(require 'ox-publish)

(setq org-publish-project-alist
      (list
       (list
    "lisp-spectrum"
    :base-directory "."
    :publishing-directory "public"
    :index-file "README.org"
    :recursive t )))

(org-publish-all t)

(dolist (f (directory-files-recursively "public" "README"))
  (rename-file f (replace-regexp-in-string "README" "index" f t) t))

still needs some cleanup and maybe more options and better styling.

[omarbassam88]

Wouldn't links also be converted to HTML's href ?

Yes, they would but they would be links to README.html rather than index.html. I found a work around, which is to link to the directory instead of linking to the README file

[omarbassam88]

Are you using org or org-roam ?

I am not using org-roam and I don't think we will need it for this. org-roam is more for note taking. The built in org functionality is enough for now.

[omarbassam88]

org

https://github.com/marketplace/actions/org-publish

I guess we don't really need this extension as we just need to run our own script.

[Malix-Labs]

Run our own script from CI ?

What would be the benefit compared to the above GitHub Action ?

See https://github.com/maker2413/OrgPublish/blob/master/publish.el

Otherwise, I could make a wrap of your proposed script for a GitHub Action

[omarbassam88]

Yeah the Github action can be something very simple for now. This is a good minimal example I think.

https://codeberg.org/SystemCrafters/systemcrafters-site/src/branch/master/.github/workflows/pull-request.yml

[Malix-Labs]

the Github action can be something very simple for now

Which ?

I do not understand how https://github.com/marketplace/actions/org-publish could not be usable

Quite frankly, I do not understand org or emacs stuff

[omarbassam88]

I do not understand how https://github.com/marketplace/actions/org-publish could not be usable

This is a custom script specific for org-roam based project. You can use it as an inspiration but not copy it exactly as it is.

[omarbassam88]

This is the actual repo of the github action you mentioned so you can learn how it's done.

https://github.com/maker2413/OrgPublish/tree/master

[omarbassam88]

Quite frankly, I do not understand org or emacs stuff

You can have a look at this tutorial if you want to understand more:

Build Your Own Website with Org Mode

Automated Org Mode Website Publishing with GitHub or SourceHut

[omarbassam88]

I've already created the publish.el script in a new branch.

https://github.com/omarbassam88/lisp-spectrum/tree/website-workflow

[Malix-Labs]

I will try to publish a decoupled GitHub Action, but I am busy until the start of september

[omarbassam88]

The website is now published on https://lisp-spectrum.org/

[Malix-Labs]

Are you publishing it with a post-commit hook or even manually ?

[omarbassam88]

Not manually. I've created a custom github action that runs on every push to main. It runs the publish.el script to build the website to a public folder and the I've set up github pages to host the website from that public folder.

[Malix-Labs]

Indeed https://github.com/omarbassam88/lisp-spectrum/blob/main/.github/workflows/publish.yml

Thanks. I'll try turning it into an importable GitHub action