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.
Carrara follows a modular design and is split across a multitude of files.
prefers-color-scheme
media feature which means
colors will change according to the user's system preferencesDuring 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.
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.
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!
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.
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.
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.
Suggestions and feedback:
Contributions to documentation:
Design: