Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alopezrivera/mirage

Literate, layer-based Emacs configuration framework designed to give you maximal maintainability, extensibility and performance.
https://github.com/alopezrivera/mirage

emacs emacs-configuration emacs-customizations emacs-lisp

Last synced: 3 months ago
JSON representation

Literate, layer-based Emacs configuration framework designed to give you maximal maintainability, extensibility and performance.

Awesome Lists containing this project

README 

        
#+STARTUP: overview

#+FILETAGS: :emacs:



#+title:Mirage



Mirage is a literate, layer-based Emacs configuration framework designed to give you maximal maintainability, extensibility and performance. All in a way you can understand and control from the ground up.



| [[./mirage/startscreen-light.png]] | [[./mirage/startscreen-dark.png]] |



*How to use Mirage*



Clone this repository to your =.emacs.d=. Write your personal configuration in =config.org=; all =emacs-lisp= source code blocks will be tangled to =init.el= every time =config.org= is saved.



*BOM*



| *Package Manager* | *Literate Emacs config*             | *Keyboard bindings*       |

| [[https://github.com/radian-software/straight.el][straight.el]]   | [[https://github.com/alopezrivera/mirage/blob/main/config.org][config.org]] (tangled to =init.el=) | Emacs + custom bindings |



* Features out of the box



The Mirage [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#base-configuration][Base Configuration]] comes with batteries included!



- [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#ui][UI]]



  Clean, minimalistic UI

- [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#themes][Themes]]



  Easily set light and dark themes, easy theme toggling and circadian theme switching between light and dark themes

- [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#dashboard][A good welcome]]



  Start screen with quick links to recent files, projects, bookmarks, registers and your weekly agenda

- [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#org-mode][Full fledged Org mode]]



  Ready for literate programming, daily planning with =org-agenda= + =org-super-agenda=, code notebooks for *any language*, your own zettelkasten with =org-roam= and more

- [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#pdf][Full fledged PDF support]]



  Annotations and highlights you can save directly to the PDF, light and dark mode, text seach and more

- [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#version-control][Magit for version control]]



  A highlight of Emacs: version-control with the best Git front-end of them all



* The Mirage Core



The backbone of Mirage, the [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#mirage-core-1][Mirage Core]], consists of the elisp code responsible for the



- Package manager, currently =straight.el=

- Config management

- Mirage [[https://github.com/alopezrivera/mirage/blob/main/mirage/mirage.org#base-configuration][Base Configuration]]



* Mirage components: Layers, Modules and Extensions



Emacs has an expansive package landscape, providing it with wide-ranging functionality. Many packages are complementary, and their configuration non-trivial.



Following the approach of [[https://github.com/doomemacs/doomemacs][Doom Emacs]] and [[https://www.spacemacs.org][SpaceMacs]], in Mirage, we combine complementary packages into units called "layers", each providing a certain set of functionality, for example: [[https://github.com/alopezrivera/mirage/blob/main/mirage.org#pdf-1][PDF handling]], [[https://github.com/alopezrivera/mirage/blob/main/mirage.org#latex-1][LaTeX editing]] and an [[https://github.com/alopezrivera/mirage/blob/main/mirage.org#ide-1][Integrated Development Environment]].



Layers are composed of:



- *Modules*: elisp code to install, load and set up an Emacs package.

- *Extensions*: custom elisp code to add functionality, define custom behaviors, etc.



*Loading components:*



#+begin_src emacs-lisp



;; Loading a layer

(mirage-layer 'org)



;; Loading a module

(mirage-module 'org-roam)



;; Loading an extension

(mirage-extend 'org-queries)



#+end_src



* Contributing



Components (layers mostly) marked with TODO in =mirage.org= have much room for improvement. For example:



- The Project interaction layer

- The IDE layer

- The LaTeX layer



Adding packages and setting up things is easy within layers! And I would love any help to make these better than they are. If you have a good setup and would like to contribute or give a suggestion you're more than welcome to! :)