User manuals

Information on how-to achieve specific results, such as installing and "getting started" with emacs-ssg (essg).

These documents are essentially a "digest" of org-mode and emacs's documentation, links to their documentation as reference, and explanations of the features and mechanisms of emacs-ssg.

References

Requirements

See requirements before installation, for "other softwares dependencies" to install first.

Installation

See installation, to get started with a new project (after having installed the required dependencies).

Build for production

To create a build folder with all pages ready to be published in production.

Usage (with the CLI)

See cli for running the project's command in a shell terminal, to build, dev (watch) and publish-pages.

New project's folder structure

See folder-structure to understand where to add content and assets files, and organize them in folders.

Javascript and CSS assets

This project adds no css or javascript by default. See assets-entry-points for getting started adding custom Javascript and CSS, to customize the feature and look of the exported project.

Note: it is currently not possible to integrate with the npm package ecosystem, such as using vite, or packages that should be bundled for productions. This project does not yet offer to "compile or transform" any assets.

CSS styles

See css, to get started adding styles for the resulting website.

Javascript code

See javascript, for the different ways to use javascript generally on the site, or in specific pages/documents.

Create pages and sub-pages (folder and file based routing)

See sub-pages to create new pages, or organize them in folders, so it reflect the resulting website's URL.

org-mode syntax and various IDEs and editors

The org-mode syntax, similar to markdown, can be used from many text editors and IDEs, to work on the content of the site (and its resulting exported outputed website pages).

Content examples with org-mode syntax

References for the syntax of content written in org mode.

org-mode syntax parsing

If needed, there are tools to parse files with org syntax in many languages, (including and javascript browser and node.js).

Default generated HTML

See default-html-markup, to learn more about HTML generated for each page of the site.

Templating

The templates page tries to list the methods to re-use pieces of content, code, logic, HTML, etc, and maybe wrap content.

Site configuration with package.json.@sctlib/emacs-ssg

See package-json-configuration for how to pass configuration from the project's package.json file, directly to org-mode (without writting emacs lisp).

Themes and SETUPFILE

How to import, create and manage themes for org-mode and essg, using the SETUPFILE directive.

Customization

For more details on the avaialble customization option s.

Using git (optional)

See git, to keep track of changes in the site's project, cooperate with others, integrate with CI/CD pipelines.

CI/CD and Deployment of the project as a site (optional, with git)

The ci-cd manul should explain how to deploy the website using Continous Integration and Deployment, to publish the project online as a website (usually can be free of charge, and pretty accessible).

Adding a (git) CMS to manage and edit the content

It should be possible to additionnaly add an headless cms to manage the content and assets of the project.

Examples

See example projects for other projects using @sctlib/emacs-ssg, org-mode (without emacs-ssg), and other things.

Development

See development instructions to contribute to this project's code and features.