{"id":14459428,"url":"https://github.com/jdtsmith/outli","last_synced_at":"2025-10-10T08:08:42.181Z","repository":{"id":66869989,"uuid":"537609182","full_name":"jdtsmith/outli","owner":"jdtsmith","description":"Simple comment-based outline folding for Emacs","archived":false,"fork":false,"pushed_at":"2025-07-28T18:30:10.000Z","size":176,"stargazers_count":131,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-10T08:08:41.142Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdtsmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-16T20:25:08.000Z","updated_at":"2025-09-19T13:03:38.000Z","dependencies_parsed_at":"2024-10-27T00:22:11.543Z","dependency_job_id":"eeaa8d80-c3dd-4a35-9a19-185090323118","html_url":"https://github.com/jdtsmith/outli","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/jdtsmith/outli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtsmith%2Foutli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtsmith%2Foutli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtsmith%2Foutli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtsmith%2Foutli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdtsmith","download_url":"https://codeload.github.com/jdtsmith/outli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtsmith%2Foutli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003294,"owners_count":26083555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-01T20:01:59.680Z","updated_at":"2025-10-10T08:08:42.162Z","avatar_url":"https://github.com/jdtsmith.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"# outli\n[![MELPA](https://melpa.org/packages/outli-badge.svg)](https://melpa.org/#/outli)\n\nSimple and stylish comment-based outlines with speed keys for Emacs.\n\u003cimg width=\"1052\" alt=\"image\" src=\"https://github.com/user-attachments/assets/a6e35266-f283-4438-9fcb-c4b9a3d0a6f8\"\u003e\n\n\n`outli` is a simple Emacs outliner for code, documents, and more which provides hierarchical hide/show, styles your headings, and emulates org-mode navigation and structure editing.  It builds on the built-in `outline-minor-mode` and is simple by design, providing just a few key additional features beyond what outline already offers:\n\n- Configurable heading syntax based on the concept of a `stem` (fixed first characters) and `repeat-char` (the number of which determines a heading's depth).  Example level-two headers include classics such as `;;;;` and `# **`, but anything's possible.\n- Default header syntax based on comment char that just works for most modes. \n- Header style options including color-matched overline and blended background color for the initial heading info.\n- `Tab` and `Shift-Tab` work just like you'd expect from org-mode to toggle headings or document visibility. \n- _Speed keys_ mirroring org-mode for easy navigation, visibility, and structure editing at headlines.  Hit `?` for the list of available keys.   Additions include `h` to hide sub-levels below the current level, and `1`-`5` to specify such a level directly. \n- Exposes headings to imenu.  A fast imenu browser like [consult-imenu](https://github.com/minad/consult) is recommended. \n\n# Configuration\n`outli` is in MELPA.  Either install from there, or clone and point `use-package` at the correct path (or use [straight](https://github.com/radian-software/straight.el), etc.).\n\n```elisp\n(use-package outli\n  ;:after lispy ; uncomment only if you use lispy; it also sets speed keys on headers!\n  :bind (:map outli-mode-map ; convenience key to get back to containing heading\n\t      (\"C-c C-p\" . (lambda () (interactive) (outline-back-to-heading))))\n  :hook ((prog-mode text-mode) . outli-mode)) ; or whichever modes you prefer\n```\n\nYou should probably not enable `outli` in `org-mode` (which by default is prevented), or with other packages which operate on headings or use similar short bindings, like outshine or pdf-tools.  If you want to disable individual modes within some larger mode hierarchy (like `text-mode`), you can either opt-in by adding them one-by-one, or include those modes in `outli-heading-config` with a disable entry; see below.\n\n# Customization\n## Headline style\nThe main variable to customize is `outli-heading-config`, where you can set the _stem_ and _repeat char_, and influence the styling, including whether to style the stem and repeat chars the same, whether to include the overline, or whether to omit styling altogether.  Note that the `t` member of this alist is the default used for all modes whih are not explicitly specified.\n\nConfigured defaults are:\n\n- **emacs-lisp-mode**: stem `;;`, repeat-char `;`\n- **tex-mode**: `%%`, `%`\n- **markdown-mode**: (empty stem), `#` \n- **org-mode**: disabled\n- **all others**: `comment-start` + a space, `*`\n\nThe custom variable `outli-blend` controls whether a blended background is used to start the headline.   After configuring `outli-heading-config`, you should restart `outli-mode` in any open buffers using it.\n\n## Style Defaults\n\nYou can set defaults for the `STYLE` and `NOBAR` properties for all modes, which take effect if these parameters are omitted or `nil` in the `outli-heading-config`; see `outli-default-style` and `outli-default-nobar`. \n\n## Speed keys\nCustomize `outli-speed-commands` to alter or disable speed keys, which work at the beginning of heading lines only (similar to org speed keys).\n\n## Folding/unfolding automatically when hopping around buffers\n\nTry `reveal-mode`; see below.\n\n# FAQ\n- **How does this relate to outline-minor-mode?**\n \n  `outli` is mostly a convenient wrapper around functionality that is already built-in to outline, adding a few things like `narrow-to-subtree` and `insert-heading-respect-content` (ala org). And of course the speed-key bindings, automatic comments-as-header patterns, and styling.\n- **How does this relate to outshine?**\n\n  Mostly just conceptually.  Outshine also provides (different) speed keys, for example.  And a lot more, much of which isn't as relevant to modern emacs.  Since it builds more directly on the built-in capabilities of outline-minor-mode, `outli` is a _much_ smaller and simpler package. \n\n- **I wish `outli` styling would update when I change themes**: This should happen automatically in Emacs 29.1 and later.  For earlier version, add the following to your `use-package` stanza:\n\n   ```elisp\n      :config (advice-add 'load-theme :after #'outli-handle-theme-change) ```\n   ```\n\n- **What is the syntax of `outli-heading-config`?** \n\n  It's an _alist_, each entry of which looks like:\n\n    `(MAJOR-MODE STEM REPEAT-CHAR STYLE NO-BAR)` to configure a mode.\n  or\n  \n    `(MAJOR-MODE . nil)` to explicitly prevent `outli` from running in this mode.\n\t\n   I recommend using the customize interface to configure `outli`: `M-x customize-group outli`.  But it may help to know:\n    - `MAJOR-MODE`: A symbol for a major mode, or parent mode from which the current mode inherits, like `'text-mode` (note: omit the single apostrophe in the customize interface: it knows it's a symbol).  A value of `t` is used to specify the default.\n    - `STEM`: A string like `\"# \"`.  The fixed \"stem\" of the headline pattern (omit quotes in customize interface).  Can also be an elisp expression which evaluates to a string.\n    - `REPEAT-CHAR`: A _character_ like `?*`.  The repeating character which specifies the level of a headline (again: no `?` needed in customize, just type the character).  Can also be an elisp expression which evaluates to a character. \n    - `STYLE`: A style flag.  `nil` for default (maximum) styling, the symbol `none` for no special styling of headlines, and `t` for matched styling between stem and repeat char.  Can be omitted (defaults to `nil`).  See also `outli-default-style`. \n    - `NO-BAR`: A flag for the overline bar.  If non-`nil`, omit the overline.  Can be omitted (defaults to `nil`).  See also `outli-default-nobar`. \n\n# Tips\n- You can use arbitrary expressions for the stem and repeat chars; they'll get evaluated at run-time.\n- It's useful to target high-level modes like `prog-mode` or `text-mode`, from which many modes inherit (see [mode-minder](https://github.com/jdtsmith/mode-minder) to get a list of your major mode hierarchy).\n- Try out the `h` key at headline start: it folds everything up to be no deeper than the current header's level. \n- To prevent `outli` from being enabled in a given mode (or family of derived modes), just include `(MODE . nil)` in `outli-heading-config`.  By default, `org-mode` is excluded in this way.\n- Some emacs tools like `isearch` are smart about folding/unfolding text as you navigate through a buffer with them.  But not all.  To fix this, you can consider enabling `reveal-mode` in buffers where you use `outli`, then tools like `xref`, etc. will reveal folded targets, re-hiding them when you navigate away.\n- I recommend `consult-org-heading` and/or `consult-outline` for quickly browsing outli headings.  You can even combine these like:\n   ```elisp\n   (defun my/consult-org-heading-or-outline ()\n    (interactive)\n    (if (derived-mode-p 'org-mode)\n        (consult-org-heading)\n      (consult-outline)))\n   ```\n\n   If you use `consult-imenu`, you might like to separate headings, by adding this to the `consult-imenu` config:\n\n   ```elisp\n     (push '(?h \"Headings\")\n        (plist-get (cdr (assoc 'emacs-lisp-mode consult-imenu-config)) :types))\n   ```\n\n# Related Packages\n- `outline-minor-mode`: The built-in minor mode for outlining documents on which `outli` builds. \n- [orgmode](https://orgmode.org): The do-everything outliner mode.\n- [outshine](https://github.com/alphapapa/outshine): A feature-full `outline-minor-mode` enhancement from which `outli` took its inspiration.  Has many legacy features. \n- [outorg](https://github.com/alphapapa/outorg): Required by `outshine`, this mode enables editing comment blocks in temporary `org-mode` buffers (the inverse of code-blocks in org).\n- See [more related packages for org-like behavior outside of org](https://orgmode.org/worg/org-tutorials/org-outside-org.html). \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdtsmith%2Foutli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdtsmith%2Foutli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdtsmith%2Foutli/lists"}