#Introduction

Carrara is first and foremost an elegant type of marble, named after the city where it's quarried, but it's also the designated name for these stylesheets — cute, right?

Carrara is used in a handful of websites, many of which are built around Org's excellent publishing facility.

Org users are the intended audience of these style sheets because they make certain assumptions about the structure of your HTML documents to be able to style them correctly.

#Design

Carrara follows a modular design and is split across a multitude of files.

• It supports the prefers-color-scheme media feature which means colors will change according to the user's system preferences
• It supports syntax highlighting for a great number of languages

During processing, common.less will import various other less style sheets which are not exported to their css counterpart. Other style sheets do get exported and they are meant to be used alongside common.css to serve a particular purpose.

For example, if a page is supposed to be an article for a blog, it should also include the blog.css style sheet which uses slightly different styling than a normal page.

On the other hand, if a page is supposed to track a set of to-dos, it should also include the indent.css style sheet, this applies varying degrees of indentation to make it easier to distinguish tasks from subtasks.

#Usage

This section outlines the two different situations where you would want to use Carrara, i.e. publishing and exporting, the former involves projects built using the ox-publish library while the latter can be achieved through the use of the export dispatcher.

#Exporting

Grab a copy of the latest release, you'll likely want to place the archive adjacent to the documents you're exporting, then unarchive the documents by running the following in a shell prompt:

$ tar xvf carrara-0.2.0.tar.gz
$ mv carrara-0.2.0/css/ css/

What follows is an example file hierarchy with report.org being the document that will leverage the recently extracted style sheets.

├── css
│   ├── blog.css
│   ├── common.css
│   └── indent.css
└── report.org

report.org can reference any one of the three style sheets using the #+HTML_HEAD or a combination of them by adding HTML_HEAD_EXTRA for any additional style sheets. It's also important that we disable the default styling provided by Org by setting the html-style property to nil.

#+OPTIONS: html-style:nil
#+HTML_HEAD: <link rel="stylesheet" href="css/common.css">

Congratulations, you're all set!

#Publishing

Download the latest release and place the unarchived contents inside your project, you can do this by running the following in a shell prompt:

$ tar xvf carrara-0.2.0.tar.gz
$ mv carrara-0.2.0/css/ css/

Next, navigate to your publishing script and add a new stylesheets project to your org-publish-project-alist definition.

(list "stylesheets"
	  :base-extension "css"
	  :base-directory "css/"
	  :publishing-directory "public/css/"
	  :publishing-function #'org-publish-attachment)

Publishing scripts are Emacs Lisp files usually processed in batch mode by a build system, the result of which should be a collection of transcoded files conforming to the project specification.

Next, disable the included style sheets, these will get in the way and lead to some visual conflicts:

(setq org-html-head-include-default-style nil)

Locate the publishing project (e.g. your blog posts project) for which you'd like to set the style sheets and append the following elements:

:html-head "<link rel=\"stylesheet\" href=\"/css/common.css\"/>"

As previously mentioned, blog posts can benefit from blog.css which gives them a neater look. Use backquotes to selectively evaluate functions within the definition of org-publish-project-alist or use the list function as shown in a previous example.

:html-head (concat "<link rel=\"stylesheet\" href=\"/css/common.css\"/>"
				   "<link rel=\"stylesheet\" href=\"/css/blog.css\"/>")

You're free to modify the stylesheets as you see fit, they're all yours now.

#Adoption

The following is a full list of self-authored and independent websites known to have adopted Carrara. Note that they may have applied their own changes to the source code, possibly deviating from the original look.

• https://grtcdr.tn
• https://liaison.grtcdr.tn
• https://darkman.grtcdr.tn
• https://giornata.grtcdr.tn
• https://e-v.srht.site

#Support

If you wish to contribute a patch, inquire about something or share your feedback, you are welcome to send an email to ~grtcdr/pub@lists.sr.ht.

If you encounter issues of any kind, please file them in the project's ticket tracker.

#Acknowledgment

Suggestions and feedback:

• Adam Porter

Contributions to documentation:

• Edgar Vincent

Design:

• Protesilaos Stavrou, authored the color palette used in syntax highlighting