@sctlib/emacs-ssg NPM

=emacs-ssg= :PROPERTIES: :CUSTOM_ID: hello :END: Is an emacs and npm static site generator package. This project should help create and publish a static website with multiple pages and assets (using emacs, org-mode and some optional dependencies).

#+begin_quote All content of a website, will not be in =.md= but in emacs's =.org= file extension, for [https://orgmode.org/]. The content of files in both of the formats is text, and they have very similar syntax. Org mode offers additional features, such as converting the content files into HTML in the context of a "website project". #+end_quote

This project is a "custom configuration" of emacs' org-mode export (publish) to HTML, with a few objectives in mind. Emacs is called when building, so org-mode can convert the files into html.

It dos not replace build tools such as =vite=, which can come after in the build pipeline.

** Usage #+begin_quote There should never be the need to run =sudo= for this program. #+end_quote To start using =emacs-ssg= with a new project:

if you don't have already, install [https://www.gnu.org/software/emacs/] (see if =emacs -h= outputs; we will never need to open this program manually, and can edit the code and content with any software we prefer. Emacs is used as built tool backend).
in a shell, create a folder for the new project =mkdir my-site=
move into the project with =cd my-site=, to get started with installation

#+begin_quote It is possible to use (or not to) this project in the javascript npm ecossytem. Generally, the idea is to call one of the files =emacs-ssg.{sh,el}= with as only argument, the command to run, =build,watch,publish-pages=. Currenyly only the shell script supports =watch=.

This project is far from perfect, and does not yet support specifying which are the "serve" and "build" functions, so it does not yet automatically integrate with build tools such as =vite=. #+end_quote

*** Installation with npm, minimal =package.json= example Inside the project folder: 1. [https://www.npmjs.com/package/@sctlib/emacs-ssg] 1. then add the npm scripts into the project's =package.json= file #+begin_src json { "scripts": { "dev": "emacs-ssg dev", "build": "emacs-ssg build", "publish-pages": "emacs-ssg publish-pages" }, "devDependencies": { "@sctlib/emacs-ssg": "^0.0.10" } } #+end_src

Where the script:

=dev= will watch for changes in the project repo, and re-build
=build= will make a new build of the project, as HTML into =./public=
=publish-pages= will refresh emacs's packages and build (used in CI/CD, when deploying the site as static pages, with gitlab, github. netlify, cloudflare etc.)

There is no auto-reload of the browser page when files are changed, you will have to manually hit "refresh page".

*** Installation with emacs' =quelpa= Alternatively, it is possible to import this project as an emacs package. It will require to [https://github.com/quelpa/quelpa] or an alternative method for emacs package management.

#+begin_src emacs-lisp (use-package :quelpa (r4 :fetcher gitlab :repo "sctlib/emacs-ssg" :upgrade t)) #+end_src

See the =emacs-ssg.el= for usage in comments.

*** =npm create @sctlib/emacs-ssg= To learn how it is possible to use this command to create a project, see the repository for the package [https://gitlab.com/sctlib/create-emacs-ssg] on gitlab.

*** Build the website for production To build a =public= folder ready for production deployment

=npm run build= will output a =./public= folder
see the =./gitlab-ci.yml='s =pages= scrip for deployment steps examples

It is possible to customise the bash environment variable =ESSG_BASE_FOLDER=, for example:

#+begin_src bash export ESSG_BASE_FOLDER="emacs-ssg" #+end_src

This example is the case of the the demo website of this project, hosted on gitlab pages and served from =sctlib.gitlab.io/emacs-ssg/=

* Add static assets (css/js/img etc.) For images, files, javascript, css, etc. static assets, everything in the folder =./assets/=, will be copied 1/1 when buiding ** css There is a hardcoded entrypoint for css, =./assets/css/index.css= referenced in the head of the HTML document. * javascript There is a hardcoded entrypoint for js, =./assets/js/index.js= and this file is imported by a script of type =module= referenced in the head of the HTML document. (what (why (how))) =emacs-ssg= commands do #+begin_quote This part is an aside into how this project works. #+end_quote **** package.json → emacs-ssg.sh This project's =emacs-ssg.el= file runs the functions associated with your project's =package.json.scripts = calling the equivalent =emacs-ssg.sh emacs-ssg.el > (emacs-ssg-)= methods.

The =dev= command does: 1. running a local web server with a tool that might be already available on the local computer (if npx of python 2/3 are installed). It serves the =./public= directory 2. using =inotifywait= to listen for changes in the =./= folder (with a ignore list like =.gitignore= in =.inotifyignore=) 3. each time a file is changed/opened/deleted, the build command is re-run (only for the ones that changed), so the resulting files in =./public= can be served.

The =build= command does: 1. reads the configuration of the site from the available information given by file names, file pathnames, =package.json.@sctlib/emacs-ssg= config object (seems it is valid json key). 2. run =(emacs-ssg-build)= in the emacs-lisp file

The =publish-pages= command does: 1. update the emacs-packages, so for example in the CI/CD environment the software is up to date 2. call the build method that results in a new build

**** emacs-ssg.sh → emacs-ssg.el From this project's package json we can see the equivalence between the =emacs-ssg= npm command (in your project's package.json), and the =emacs-ssg.sh= script (exported, and used, by this project). #+begin_src json "scripts": { "dev": "./emacs-ssg.sh dev", "build": "./emacs-ssg.sh build", "publish-pages": "./emacs-ssg.sh publish-pages", "preview": "./emacs-ssg.sh preview", "test": "echo \"Error: no test specified\" && exit 1" }, #+end_src

When imported in an other project, this project exports the shell script as a bin, so it can be used as a npm command. #+begin_src json "bin": { "emacs-ssg": "./emacs-ssg.sh", "emacs-ssg-el": "./emacs-ssg.el" }, #+end_src

This is how =@sctlib/emacs-ssg= can be imported as a npm package in an other npm project.

To try calling emacs's command directlym without going through the call to =npm run = which calls the shell script, run:

#+begin_src shell emacs --batch --no-init-file --load ./emacs-ssg.el --funcall ssg-build

in --bath mode

withough the user's possible existing init file in ~/.emacs.d/ etc.

use the file specified by --load for where our "SSG project code" is

and --funcall is the name of the invoqued function, from that file

this is an excerpt of the emacs-ssg.sh shell script

Alternativelly, the lisp file can be called as a script

./emacs-ssg.el build #+end_src

** Project folder/file structure:

=content/*=, all text content, pages and examples for your site
=assets/*= a folder with our static =.js= and =.css= content
=emacs.el=, the config file that describes how make a website out of this project's content. Currently only this project's is read (we could imagine having the a file with the same name in the project's folder, to be read as well; like the paackage.json is)
=.gitlab-ci.yml=, a config file, used to define what commands should be called to publish this project as as website on a gitlab pages server

the =./content/= folder In this folder, each =.org= file is converted to a static =.html= page in the resulting "built" site. the =./assets/= folder All static assets used by the site. =index.js= and =index.css= are hardcoded, the rest is free to add and import.

** Customization To customize 100% the resulting website, the build process, how each files are handled, [https://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html] and [https://orgmode.org/manual/Export-Settings.html].

It is practical to be introduced with emacs and emacs-lisp for the =.el= file; here are some ressources to get started:

[https://www.emacswiki.org/emacs/OrgMode]
[https://www.emacswiki.org/emacs/LearnEmacsLisp]
[https://www.youtube.com/@SystemCrafters]
[https://www.youtube.com/watch?v=RQK_DaaX34Q]
[https://www.gnu.org/software/emacs/manual/html_node/eintr/]
[https://www.gnu.org/software/emacs/tour/]

*** HTML export and customize a specific page To customize [https://orgmode.org/manual/HTML-Export.html] it is also possible to add specific [https://orgmode.org/manual/HTML-specific-export-settings.html] in a =.org= file "header".

At the top of the file, add for example the directive =#+HTML_HEAD:= followed by a space, and the custom HTML tag you'd like to insert, such as:

#+begin_src text #+HTML_HEAD: #+end_src

For bare-html project see how to have the most [https://orgmode.org/manual/Bare-HTML.html] as ssg-build function.

*** html =a= anchor links

[https://orgmode.org/manual/Links-in-HTML-export.html]
[https://orgmode.org/manual/Internal-Links.html]
[https://orgmode.org/manual/Radio-Targets.html]
[https://orgmode.org/manual/Publishing-links.html]
[https://orgmode.org/manual/Handling-Links.html]
[https://orgmode.org/guide/Hyperlinks.html]

*** html quoting

[https://orgmode.org/manual/Quoting-HTML-tags.html] *** textareas It is possible to handle [https://orgmode.org/manual/Text-areas-in-HTML-export.html] in a org file.

*** More org-mode can do a lot of other things:

[https://orgmode.org/manual/]
[https://orgmode.org/manual/Extracting-Source-Code.html]
[https://stackoverflow.com/questions/9559753/emacs-org-mode-export-to-another-directory]

** org-mode info js

[https://orgmode.org/manual/JavaScript-support.html]

** Other tips

To export to pdf in the browser, use Firefox's "print" page feature ("save file to pdf").

This project can also be openned with [https://www.gnu.org/software/emacs/]. When the file =index.org= is oppenned, it gives access to the following shortcuts.

select export format =C-c C-e= (txt, html etc.)
export to =.txt=: =C-c C-e t A=

Objectives Building websites can lead to using various static site generators, single-page javascript frameworks, build tools, and specificities. We would like to offer a way to get starting with a website, that has a clean base and offers default features.

Should be as intuitive and inclusive as possible
No magic, it should be clear how/when/why things work (and if are "transformed")
Separation of content and clear folder/file structure
File based routing, based on content files
default modern HTML, CSS, Javascript (use web components?)
chose your tools (for build, development etc.)
take advantage of org-mode and emacs (and create documentation for SSG usage)
clear path to learning, creating, publishing, maintaing static web-pages