Table of Contents

• jcs-emacs
  • Philosophy
  • 📰 News
  • 💾 Installation
  • 🕒 Startup Time
  • 🏆 Features
    • Highlight
    • Details
  • 📁 Package Archives
  • 🏆 Powered by
    • Functionalities
    • File Modes
  • Key Bindings
  • Themes
    • Default
    • Customization
  • Font
  • 🔨 Optimization
  • Write your own customization
  • 🎍 Supported Emacs versions
  • ❓ FAQ
  • Contribute

jcs-emacs

Consistent Emacs configuration for all platforms.

This is Jen-Chieh Shen's emacs configuration. This configuration started from Casey Muratori's Emacs configuration. It has been repeatedly utilized and modified since 2015 and is now very different to his configuration.

I wouldn't claim this is the best Emacs config, but this is the best config to myself. If you wish to learn Emacs, this could be a good start, because this configuration has been rewritten basically from scratch. Hopefully, this config will help someone who is new or struggle to Emacs. This configuration should work on most OSs, indicates Windows, macOS, and Linux.

Emacs itself supports multiple programming languages. I managed all the programming languages I personally used. I dabble in numerous technologies, incorporate hardware, firmware and software. Here is the list of programming languages I know and are extended from this configuration.

• ActionScript 2.0 or 3.0 / Ada / Agda / AppleScript / Assembly Language
• BASIC / Batchfile
• C / C++ / C# / Clojure / CMake / COBOL / CSS
• Dart / Dockerfile
• Elixir / Elm / Emacs Lisp / Erlang
• F# / Fountain
• GLSL / Go / GDScript / Groovy
• Haskell / Haxe / HTML
• INI
• Java / JavaScript / JSON / JSX
• Kotlin
• LESS / Lisp / Lua
• Makefile / Markdown
• Nix
• Object Pascal (Delphi) / Objective-C
• Pascal / Perl / PHP / PowerShell / Properties / Python
• R / Ruby / Rust
• Sass / Scala / SCSS / Shader / Shell script / SQL / Swift
• TOML / TSX / TypeScript
• Verilog / Vimscript / Vue
• XML
• YAML

This configuration polished and goes toward to the modern text editor, or even better, it goes beyond modern IDE. e.g. Atom, Brackets, Sublime Text 2 or 3, Visual Studio Code, etc.

Philosophy

I have experienced many different kinds of IDEs and text editors. But I’ve had a hard time finding the best tool to use. I’ve jumped from one working field to another trying to find something that suits my needs. So instead of struggling with the tool itself, I chose Emacs and configured the entire thing from scratch, to suit my needs.

Here are a few goals that I want this config to accomplished.

• Having the same set of key bindings across different IDEs and text editors as many as possible.
• Having the same font and theme across different OSs and environments.
• Automating trivial or redundant tasks.
• Improve user experiences approach to modern text editor or IDE.
• Make compatible to most features work inside terminal as well.

Having these implementations makes my life easier, and having a genuinely portable workspace, which is great because it lets me work on different machine efficiently, without having to get used to an new IDE.

📰 News

Here is the list of few important and recent changes to this configuration.

• 8.0.0 - Move everything to .emacs.d. (#32)
• 7.1.0 - Replace quelpa with github-elpa.
• 7.0.0 - Switch from quickhelp to box for company frontend.
• 6.5.0 - Add pinned archive feature to package module.
• 6.4.2 - You can now resolve package dependency graph while deleting package.
• 6.4.1 - Start with tree-sitter support.
• 6.4.0 - Switched from projectile to built-in project for project management.
• 6.3.1 - Replaced docstring module to external docstr package.
• 6.2.5 - Use recipes folder instead to specify manually installed packages in the configuration.
• 6.2.4 - Replaced ag silver searcher to searcher.

💾 Installation

To install, clone this repo to ~/.emacs.d, i.e. ensure that the init.el contained in this repo ends up at ~/.emacs.d/init.el:

git clone https://github.com/jcs-emacs/jcs-emacs ~/.emacs.d

Then startup Emacs; it will automatically installs all necessary packages due to this configuration.

❗❗ [ATTENTION] ❗❗ -- MAKE SURE YOU INSTALLED THE CORRECT VERSION OF EMACS!

🕒 Startup Time

The average startup time for this configuration is around 15 to 25 seconds. You can use command emacs-init-time to check the startup time on your machine. Not quite sure what causes that much of performance, hopefully, I'm able to lower the startup time down to 5 to 15 seconds.

Edit 1: After version 5.3.2, the average startup time is around 5 to 15 seconds. Solved this issue by removing unnecessary require keyword load file and use :defer keyword with use-package package to delay some packages load time.

📝 P.S. Here is a great article about Speeding Up Emacs written by Anurag Peshne.

Edit 2: If you compiled the source code then the startup time can lower down more from 0.5 to 1.5 seconds.

Edit 3: Using esup package to test and optimize the configuration. Call package-refresh-contents only when package installation is needed. By doing thing, lower the startup time from around 4 to 8 seconds.

📝 P.S. Some good hints from one StackExchange question, What can I do to speed up my start-up? answered by Jordon Biondo.

📝 P.S. The above cases are tested on Windows. Other OS that are not Windows should start up under a second.

🏆 Features

Highlight

Here is the list of the major highlights to this configuration. Hope you would like my taste!

• Out of the box - Out of the box anywhere.
• Cross Platform - Work on all operating system including terminal.
• Fast Startup - Lazy loading for all unnecessary packages on startup.
• Old-Fashioned - Doesn't use any beatiful GUI because it may not work in terminal.
• Multiple Languages - Support multiple programming languages.
• Consistent - Having the same coding experience in different major mode.
• Easy to use - Design close to other modern text editors. Shouldn't spend you too much time.
• Dual Windows - Design to people who like multiple windows opened simultaneously.
• Keyboard Focused - You can do everything by using keyboard and mouse are just optional.

Details

This is the list of features that are built-in to this configuration. These features are heavily base on my personal habits, and so these could be very tiny things. But I believed detials make things better and make life smoother.

• Auto Install Package - Automatically installs the package that this config relies on.
• Better Dashboard - Implementation for improving experiences using dashboard.
• Buffer Menu Search - Able to search in the *Buffer List* buffer.
• Build Run - Implementation for executing script for building and running the software.
• Capital Word - You can navigate/kill word by seeing capital letter.
• Changelog Helper - Help to create changelog while creating CHANGELOG file using template.
• Consistent Key Bindings - Has consistent key bindings across all modes.
• Curly Bracket Modes - Use curly bracket depends on different mode.
• Display File - Utility function to use to view a file on the other window.
• Charset Table - Built-in functions that displays character sets.
• Docstring Completion - Some standard docstring completion implementations built-in to this configuration. (has move to docstr)
• Enhanced Multiple Cursors
  • Similar Multiple Cursors - Mark with cursor by similarity.
  • VS Multiple Cursors - VSCode like methods to mark and unmark multiple cursor.
• Fast Incremental Search - Fast keys for incremental search forward/backward to the cursor is currently pointing.
• Indent Control - Generic control the indentation level for each mode, for more information see indent-control.
• Previous/Next Keys
  • Normal Move - Act like other normal editors.
  • Indent Move - Automatically indent when cursor moves up and down.
  • Smart-Move - Smart enough to move cursor to the beginning of the line.
• Line Numbers Modding - Mixed used of linum and display-line-numbers-mode base on the file usage.
• License Helper - Help to create license while creating LICENSE file using template.
• Mini State - Mini mode state use to visually see what backend is the config currently running. (Deprecated)
  • Explicit States - Automatcially switch mini state depends on certain circumstances.
• Mode Line Toggle - Toggle to show or hide the mode line.
• Modern Text Editor - Design to have the preset settings close to modern text editors but faster.
• Multiple Output - Handle multiple output/compilation buffers.
• Navigate Blank Line - Use C-<up> and C-<down> to navigate previous and next blank line.
• Navigate Table - Navigate org-mode's table easier by using arrow keys.
• Preview HTML - Preview rendered HTML file on the other window.
• Simulate Shell - Completely simulate shell behaviors, make better user experience when using shell in Emacs.
• Switch Window - Fast keys switch between windows quickly.
• Tabify/Untabify Modes - Tabify or Untabify the file depends on the mode you currently in.
• Transparent Window - Keys to increase/decrease the transparency of the frame. (has move to transwin)
• Trim Trailing Whitespace - Remove trailing spaces and tabs automatically on save.
• Video Player - Play media on the top window.
• Visualize Undo/Redo - Improved the user experience on undoing and redoing by showing the undo-tree-visualizer at the other window.
• VS Curly Bracket - Visual Studio IDE like curly bracket implementation.
• VS Multiple Terminal - VSCode like multiple shell control.
• VS Navigate Word - Visual Studio IDE like navigating between word implementation.

📁 Package Archives

A list of package archives that this configuration uses.

• ELPA - Emacs Lisp Package Archive
• MELPA - Milkypostman’s Emacs Lisp Package Archive
• elpa (jcs) - Emacs Lisp Package Archive for this configuration

📝 P.S. Here is a good talk comparing all package archives from a StackExchange question, What are the practical differences between the various Emacs Package Repositories? answered by Tikhon Jelvis.

🏆 Powered by

Here is the list of all packages that powered and make this configuration works. Thanks to all the package maintainers; this configuration cannot be made without them, and if you wish to support them you can go to this elisp-maintainers repo/site and search for the maintainer you want to support. There should be some kind of methods that you could support the maintainer you want.

Functionalities

• Abbreivation Definition - powered by project-abbrev.
• Alt-Codes - powered by alt-codes.
• Auto Completion - powered by company.
• Auto Highlight Symbol - powered by auto-highlight-symbol-mode.
• Banner - powered by dashboard.
• Binary/Hex Editor - powered by nhexl-mode.
• Collaborative Editing - powered by togetherly.
• Completion Frontend - powered by ivy.
• Context Menu - powered by right-click-context.
• Document String - powered by docstr.
• End of Line - powered by show-eol.
• Execute Commands - powered by compile.
• File Explorer - powered by treemacs.
• File Header - powered by file-header.
• Folding/Unfolding - powered by ts-fold.
• Font - powered by use-ttf.
• Goto Declaration/Definition - powered by dumb-jump.
• Highlight Indentation - powered by highlight-indent-guides.
• Highlight Matched Pairs - powered by show-paren-mode.
• Highlight Same Region - powered by region-occurrences-highlighter.
• Indentation Management - powered by indent-control.
• Language Server Protocol - powered by lsp-mode.
• Line Annotation - powered by line-reminder.
• Line Numbers - powered by display-line-numbers and linum.
• Minimap - none, originally powered by sublimity.
• Mode Line - powered by powerline.
• Multiple Cursor - powered by iedit and multiple-cursors.
• Multiple Terminal - powered by multi-shell.
• Music Player - none.
• Navigation/Searcher - powered by searcher and isearch-project.
• Package Archive - see here.
• Package Management - powered by leaf and github-elpa.
• PDF Viewer - powered by doc-view-mode and ghostscript.
• Project Management - powered by project.
• Recent Files - powered by recentf.
• Regexp - powered by re-builder and visual-regexp.
• Restart Emacs - powered by restart-emacs.
• Scroll Bar - powered by yascroll.
• Shell - powered by shell and exec-path-from-shell.
• Smooth Scrolling - none, originally powered by sublimity.
• Snippet - powered by yasnippet.
• Source Control Management - powered by magit.
• Startup Screen - powered by dashboard.
• Syntax Check - powered by flycheck.
• Tab Bar - powered by centaur-tabs.
• Tags - powered by gtags.
• Text Editing - powered by org-mode.
• Theme - powered by vs-dark-theme and vs-light-theme. (For more info see here)
• Todo - powered by hl-todo.
• Toggle Mode Line - powered by feebleline.
• Undo/Redo - powered by undo-tree.
• Video Player - none.
• White Space - powered by whitespace.

Write your own customization

You are able to customize the configuration by editing the file locate at ~/.emacs.d/site-lisp/jcs-config.el. You should put all your own customize code there, then other than that are the core files.

🎍 Supported Emacs versions

The config should run on Emacs 27.1 or higher, but I will recommend to always run on the latest Emacs version available on your machine. The ultimate goal is to design to have each version of config can run on their each according Emacs version base on the version what I'm currently running on my present machine. For each version record, you can check the version_record file at the root of the project directory.

❓ FAQ

Here is the list of Frequently Asked Questions.

• List of FAQ

Contribute

If you would like to contribute to this project, you may either clone and make pull requests to this repository. Or you can clone the project and establish your own branch of this tool. Any methods are welcome!