Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/alphapapa/org-make-toc

Automatic tables of contents for Org-mode files
https://github.com/alphapapa/org-make-toc

emacs org-mode

Last synced: 1 day ago
JSON representation

Automatic tables of contents for Org-mode files

Awesome Lists containing this project

README 

        
#+PROPERTY: LOGGING nil



* org-make-toc

:PROPERTIES:

:TOC:      ignore

:END:



[[https://melpa.org/#/org-make-toc][file:https://melpa.org/packages/org-make-toc-badge.svg]] [[https://stable.melpa.org/#/org-make-toc][file:https://stable.melpa.org/packages/org-make-toc-badge.svg]]



This package makes it easy to have one or more customizable tables of contents in Org files.  They can be updated manually, or automatically when the file is saved.  Links to headings are created compatible with GitHub's Org renderer.



* Contents                                                         :noexport:

:PROPERTIES:

:TOC:      :include siblings :depth 0 :ignore this

:END:

:CONTENTS:

- [[#installation][Installation]]

- [[#usage][Usage]]

- [[#changelog][Changelog]]

:END:



* Installation



** MELPA



If you installed from MELPA, you're done.



** Manual



  Install these required packages:



+  =dash=

+  =s=



  Then put this file in your load-path, and put this in your init file:



#+BEGIN_SRC elisp

  (require 'org-make-toc)

#+END_SRC



* Usage



A document may have any number of tables of contents (TOCs), each of which may list entries in a highly configurable way.



To make a basic TOC, follow these steps:



1.  Choose a heading to contain a TOC and move the point to it.

2.  Run command =org-make-toc-insert=, which inserts a =:CONTENTS:= drawer and sets TOC properties.  Set the =include= property to =all=.

3.  Run the command =org-make-toc= to update all TOCs in the document.



Use command =org-make-toc-set= to change TOC properties for the entry at point with completion.



** Example



Here's a simple document containing a simple TOC:



#+BEGIN_SRC org

  ,* Heading

  :PROPERTIES:

  :TOC:      :include all

  :END:



  This text appears before the TOC.



  :CONTENTS:

  - [[#heading][Heading]]

    - [[#subheading][Subheading]]

  :END:



  This text appears after it.



  ,** Subheading

#+END_SRC



** Advanced



The =:TOC:= property is a property list which may set these keys and values.



These keys accept one setting, like =:include all=:



+  =:include= Which headings to include in the TOC.

     -  =all= Include all headings in the document.

     -  =descendants= Include the TOC's descendant headings.

     -  =siblings= Include the TOC's sibling headings.

+  =:depth= A number >= 0 indicating a depth relative to this heading.  Descendant headings at or above this relative depth are included in TOCs that include this heading.



These keys accept either one setting or a list of settings, like =:force depth= or =:force (depth ignore)=:



+  =:force= Heading-local settings to override when generating the TOC at this heading.

     -  =depth= Override =:depth= settings.

     -  =ignore= Override =:ignore= settings.

+  =:ignore= Which headings, relative to this heading, to exclude from TOCs.

     -  =descendants= Exclude descendants of this heading.

     -  =siblings= Exclude siblings of this heading.

     -  =this= Exclude this heading (not its siblings or descendants).

+  =:local= Heading-local settings to ignore when generating TOCs at higher levels.

     -  =depth= Ignore =:depth= settings.



See [[https://github.com/alphapapa/org-make-toc/blob/master/example.org][example.org]] for a comprehensive example of the features described above.



** Automatically update on save



To automatically update a file's TOC when the file is saved, use the command =add-file-local-variable= to add =org-make-toc= to the Org file's =before-save-hook=.



Or, you may activate it in all Org buffers like this:



#+BEGIN_SRC elisp

  (add-hook 'org-mode-hook #'org-make-toc-mode)

#+END_SRC



** Making links work in both Emacs/Org and on GitHub



Because of the way GitHub renders Org documents and links, it's not possible to make links which work in both Org itself and the GitHub-rendered HTML unless headings have ~CUSTOM_ID~ properties.  If the option ~org-make-toc-insert-custom-ids~ is enabled, this package will automatically add them as needed.



* Changelog

:PROPERTIES:

:TOC:      :depth 0

:END:



** 0.6



*Compatibility*

+ Org 9.3 or later is now required.



*Additions*



+ Option ~org-make-toc-insert-custom-ids~ automatically adds ~CUSTOM_ID~ properties to headings so links can work on both GitHub-rendered Org files and in Emacs.  (Thanks to [[https://github.com/noctuid][Fox Kiester]].)



*Fixes*



+ Tolerate whitespace before drawer opening/closing lines.  ([[https://github.com/alphapapa/org-make-toc/pull/15][#15]], [[https://github.com/alphapapa/org-make-toc/issues/17][#17]].  Thanks to [[https://github.com/progfolio][Nicholas Vollmer]].)

+ Link-type function called with position as argument.  (Fixes occasional bugs with heading IDs.)

+ Mode ~org-make-toc-mode~ now adds to the ~before-save-hook~ in the local buffer rather than globally.  ([[https://github.com/alphapapa/org-make-toc/pull/24][#24]].  Thanks to [[https://github.com/akirak][Akira Komamura]].)



** 0.5



This version is a major rewrite that requires reconfiguring existing TOCs.  Please see the usage instructions anew.  Users who don't want to convert to 0.5-style TOCs may continue using version 0.4.



*Changes*

+  TOCs are now contained in =:CONTENTS:= drawers, which allows them to co-exist with entry content and be placed flexibly.

+  The =:TOC:= property, which contains all TOC settings, is now formatted like a Lisp property list, and the settings have been redesigned to be clearer, more concise, more flexible, and more powerful.



** 0.4



*Additions*

+  Omit invisible characters from link titles (e.g. Org markup characters like ~=~ and =~=).

+  Option ~org-make-toc-link-type-fn~ allows choosing GitHub-compatible or regular Org-style links.

+  Command =org-make-toc-at-point=, which updates the TOC at the current entry.

+  Optionally place TOC in a =:CONTENTS:= drawer which co-exists with entry content.



*Changes*

+  Changed no-TOC-node-found error to a message, so e.g. when =org-make-toc-mode= is active in a buffer without a TOC, saving will not signal an error.



*Fixes*

+  Remove excess indentation from TOC while preserving list structure.

+  Don't insert a blank line when TOC is empty.

+  Autoload minor mode.  (Thanks to [[https://github.com/akirak][Akira Komamura]].)

+  Filename prefix order in links.  (Thanks to [[https://github.com/dakra][Daniel Kraus]].)



** 0.3.1



*Fixes*

+  Use =cadr= instead of =second=.



** 0.3



*Additions*

+  Option ~org-make-toc-filename-prefix~ to add the filename before the anchor in links.  This allows a ToC to refer to entries in another file by manually copying a ToC from one file into another.  See [[https://github.com/alphapapa/org-make-toc/pull/2][issue 2]].  Thanks to [[https://github.com/dakra][Daniel Kraus]].



*Changes*

+  Minor refactoring.



** 0.2



*Additions*

+  Multiple tables of contents are now supported in a single document.

+  Entries' =TOC= property can now also be set to the values =all=, =children=, and =siblings=, which allow tables of contents to be created for only parts of a document.

     -  =all= includes all entries in a document, including other tables of contents, except ignored entries.

     -  =children= includes only child entries, except ignored entries.

     -  =siblings= includes only sibling entries, except ignored entries.

+  The command =org-make-toc-mode= toggles =org-make-toc= on the =before-save-hook= in the current buffer.  This may be added to the global =org-mode-hook= to activate it in every Org buffer.

+  The =examples.org= file shows an example of all of the options used together in a complex, book-like document.



** 0.1



Initial release.



* Credits

:PROPERTIES:

:TOC:      :ignore this

:END:



This package was inspired by Sergei Nosov's [[https://github.com/snosov1/toc-org][toc-org]] package.



* Development

:PROPERTIES:

:TOC:      :ignore this

:END:



Bug reports, feature requests, suggestions — /oh my/!



* License

:PROPERTIES:

:TOC:      :ignore this

:END:



GPLv3



# Local Variables:

# eval: (require 'org-make-toc)

# before-save-hook: org-make-toc

# org-export-with-properties: ()

# org-export-with-title: t

# End: