SystemCrafters / crafted-emacs

A sensible base Emacs configuration.
MIT License
743 stars 117 forks source link

+title: Crafted Emacs

  1. [[#description][Description - What is this anyway?]]
  2. [[#philosophy][Philosophy]]
    1. [[#goals][Goals]]
    2. [[#principles][Principles]]
  3. [[#getting-started][Getting Started]]
  4. [[#contributing][Contributing]]
  5. [[#troubleshooting][Troubleshooting]]
  6. [[#license][License]]

Crafted Emacs is an attempt to simplify creating a configuration for Emacs. It is not intended to provide all possible configuration for every eventuality. We do envision it being a nice baseline for users who want to create their own Emacs configuration. As a user develops their skill with Emacs Lisp and configuring Emacs in general, we anticipate such a person may end up rewriting their configuration to the point they are no longer using Crafted Emacs. This is an exciting possibility to us, and a journey worth taking!

It is our opinion your configuration is, well, yours! We expect you to own your configuration, but maybe we can help get you started. In the space of "starter kits" for Emacs, we really take to heart the word "starter", in the sense we help you start your configuration. We aren't the kitchen sink and we don't provide every possible configuration. That's your job. It's YOUR configuration.

** Goals :properties: :custom_id: goals :end:

** Principles :PROPERTIES: :custom_id: principles :END:

*** Minimal, modular configuration

The core configuration only sets up Emacs to have a cleaner presentation with sensible defaults. It is up to the user to decide which ~crafted-*~ modules to load.

Configuration modules depend on other modules and the base configuration as little as possible.

The implication is that someone should be able to install or copy code from a ~crafted-*~ module into their own configuration /without/ using Crafted Emacs.

*** Prioritize built-in Emacs functionality

Where possible, we leverage built-in Emacs functionality instead of external packages. When we choose external packages, we prefer those which are layered on top of existing, built-in, functionality. For example:

*** Can be integrated with a Guix configuration

It should be possible to customize aspects of the Crafted Emacs configuration inside of a Guix Home configuration so that things like font sizes, themes, etc can be system-specific.

It can also use packages installed via the Guix package manager instead of ~package.el~.

*** Helps you learn Emacs Lisp

Instead of providing a higher-level configuration system out of the box like other Emacs configurations, we follow standard Emacs Lisp patterns so that you can learn by reading the configuration. We do our best to provide clear comments where necessary to help the reader understand our choices and how the code works.

*** Reversible

We recognize not everyone will agree with our decisions, so each customization should be easily reversible in the users configuration file.

Generally, getting started with Crafted Emacs is as simple as cloning the project from GitHub:

+begin_src sh

git clone https://github.com/SystemCrafters/crafted-emacs

+end_src

After cloning the Crafted Emacs repo, to use the modules, you need to add the following to your configuration:

+begin_src emacs-lisp

;; This assumes you cloned Crafted Emacs in you home directory, if you ;; didn't, make sure to update the path to correctly reflect the ;; location on your system. (load "~/crafted-emacs/modules/crafted-init-config")

+end_src

This adds the ~crafted-emacs/modules~ folder to the ~load-path~. If you need to have packages installed, look for modules ending with ~-packages.el~, if you only want the configuration, then the modules ending with ~-config.el~ will be what you want.

For more detailed examples, see the [[file:docs/getting-started-guide.org][Getting Started Guide]]. There are also examples in the ~crafted-emacs/examples~ folder.

This is a community-run modular Emacs configuration, for which we appreciate feedback in the form of issues and pull requests. Feel free to open an issue prior to opening a pull request if you're not certain your idea is in the spirit of the [[#principles][Principles]].

If you enjoy crafting your computing experience, join the [[https://systemcrafters.net/][SystemCrafters]] community!

** Contributing Tips for Elisp

** Contributing Tips for Issues

We welcome your questions and ideas, please open an issue if you have one!

Pease keep in mind, we only support released versions of Emacs. Development versions of Emacs may have incompatibilities, defects or incomplete features. Trying to support development versions of Emacs is like shooting at a moving target; not impossible, but a lot more difficult than may be expected. Applying changes to Crafted Emacs to accomodate development versions of Emacs may break things for those who use a released version.

** A package (suddenly?) fails to work

This scenario happened frequently when upgrading to Emacs 28. It also may occur in other scenarios as well. Usually, you will see some message indicating some symbol is void or some function or command does not exist. More often than not, the package maintainer is using a feature from another package which has not yet been released. The new feature is available in the development version of the package however.

Here are some example issues where things went wrong:

This code is licensed under the MIT License. Why? So you can copy the code from this configuration!


Local Variables:

fill-column: 80

eval: (auto-fill-mode 1)

End: