{"id":13570942,"url":"https://github.com/snosov1/toc-org","last_synced_at":"2025-04-04T07:32:29.306Z","repository":{"id":30693864,"uuid":"34249829","full_name":"snosov1/toc-org","owner":"snosov1","description":"toc-org is an Emacs utility to have an up-to-date table of contents in the org files without exporting (useful primarily for readme files on GitHub)","archived":false,"fork":false,"pushed_at":"2023-08-31T07:52:49.000Z","size":155,"stargazers_count":294,"open_issues_count":11,"forks_count":30,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-05T03:36:58.229Z","etag":null,"topics":["emacs","emacs-lisp","github","org","org-mode","readme","toc"],"latest_commit_sha":null,"homepage":null,"language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"nisrulz/flutter-examples","license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snosov1.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-04-20T09:00:46.000Z","updated_at":"2024-10-14T14:32:34.000Z","dependencies_parsed_at":"2024-01-14T03:50:18.323Z","dependency_job_id":"3ddb7d2f-a718-49d5-9576-548c44fb8627","html_url":"https://github.com/snosov1/toc-org","commit_stats":{"total_commits":104,"total_committers":10,"mean_commits":10.4,"dds":"0.17307692307692313","last_synced_commit":"bf2e4b358efbd860ecafe6e74776de0885d9d100"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snosov1%2Ftoc-org","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snosov1%2Ftoc-org/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snosov1%2Ftoc-org/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snosov1%2Ftoc-org/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snosov1","download_url":"https://codeload.github.com/snosov1/toc-org/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247139190,"owners_count":20890183,"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","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":["emacs","emacs-lisp","github","org","org-mode","readme","toc"],"created_at":"2024-08-01T14:00:56.737Z","updated_at":"2025-04-04T07:32:24.297Z","avatar_url":"https://github.com/snosov1.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"[[https://travis-ci.org/snosov1/toc-org][file:https://api.travis-ci.org/snosov1/toc-org.svg?branch=master]]\n\n* About\n\n=toc-org= helps you to have an up-to-date table of contents in org files without\nexporting (useful primarily for readme files on GitHub).\n\nIt is similar to the [[https://github.com/ardumont/markdown-toc][markdown-toc]] package, but works for org files. Since\nrecently, =toc-org=, actually, works in [[#markdown-support][markdown]], too!\n\n*NOTE:* Previous name of the package is =org-toc=. It was changed because of a\nname conflict with one of the org contrib modules.\n\n* Table of Contents                                                     :TOC:QUOTE:\n#+BEGIN_QUOTE\n- [[#about][About]]\n- [[#installation][Installation]]\n  - [[#via-packageel][via package.el]]\n  - [[#manual][Manual]]\n- [[#use][Use]]\n  - [[#follow-links][Follow links]]\n  - [[#exclude-headings][Exclude headings]]\n  - [[#quote-table-of-contents][Quote table of contents]]\n  - [[#shortcut-for-toc-tag][Shortcut for TOC tag]]\n- [[#markdown-support][Markdown support]]\n- [[#different-href-styles][Different href styles]]\n- [[#example][Example]]\n#+END_QUOTE\n\n* Installation\n** via package.el\n\n[[https://elpa.nongnu.org/nongnu/toc-org.html][https://elpa.nongnu.org/nongnu/toc-org.svg]]\n[[http://melpa.org/#/toc-org][file:http://melpa.org/packages/toc-org-badge.svg]]\n\nThis is the simplest method if you have the package.el module (built-in since\nEmacs 24.1) you can simply use =M-x package-install= after setting up the [[http://melpa.org/#/getting-started][MELPA]]\nrepository and then put the following snippet in your ~/.emacs file\n\n#+BEGIN_SRC elisp\n  (if (require 'toc-org nil t)\n      (progn\n        (add-hook 'org-mode-hook 'toc-org-mode)\n\n        ;; enable in markdown, too\n        (add-hook 'markdown-mode-hook 'toc-org-mode)\n        (define-key markdown-mode-map (kbd \"\\C-c\\C-o\") 'toc-org-markdown-follow-thing-at-point))\n    (warn \"toc-org not found\"))\n#+END_SRC\n\n** Manual\n\n- Create folder ~/.emacs.d if you don't have it\n- Go to it and clone toc-org there\n  #+BEGIN_SRC sh\n    git clone https://github.com/snosov1/toc-org.git\n  #+END_SRC\n- Put this in your ~/.emacs file\n  #+BEGIN_SRC elisp\n    (if (require 'toc-org nil t)\n        (progn\n          (add-hook 'org-mode-hook 'toc-org-mode)\n\n          ;; enable in markdown, too\n          (add-hook 'markdown-mode-hook 'toc-org-mode)\n          (define-key markdown-mode-map (kbd \"\\C-c\\C-o\") 'toc-org-markdown-follow-thing-at-point))\n      (warn \"toc-org not found\"))\n  #+END_SRC\n\n* Use\n\nAfter the installation, every time you'll be saving an org file, the first\nheadline with a =:TOC:= tag will be updated with the current table of contents.\n\nTo add a TOC tag, you can use the command =org-set-tags-command= (=C-c C-q=).\n\nIn addition to the simple :TOC: tag, you can also use the following tag formats:\n\n- :TOC_2: - sets the max depth of the headlines in the table of contents to 2\n  (the default)\n\n- :TOC_2_gh: - sets the max depth as in above and also uses the GitHub-style\n  hrefs in the table of contents (this style is default). The other supported\n  href style is 'org', which is the default org style.\n\nYou can also use =@= as separator, instead of =_=.\n\nIt's possible to set the default values of max depth and hrefify function with\n=toc-org-max-depth= and =toc-org-hrefify-default= variables. But, note, that if\nyou do this outside of the org file itself, then you can face conflicts if you \nwork on the same file collaboratively with someone else, as your default configs \ncan vary.\n\n** Follow links\n\nIf you call =M-x org-open-at-point= (=C-c C-o=) when you're at a TOC entry, the\npoint will jump to the corresponding heading.\n\nNotice, that this functionality exploits the =org-link-translation-function=\nvariable. So, it won't work if you use this variable for other purposes (i.e. it\nis not nil).\n\nYou can manually disable this functionality by setting\n=toc-org-enable-links-opening= to nil.\n\n** Exclude headings\n\nHeadings tagged with =:noexport:= will be excluded from the TOC. If you want to\npreserve the heading, but strip its children (for changelog entries, for\nexample), you can tag it =:noexport_1:= (by analogy, you can use =:noexport_2:=,\n=:noexport_3:=, etc. for children of deeper levels). Note, though, =:noexport:=\nhas a similar meaning in =org-mode=, which I hope is a Good Thing (tm). However,\n=:noexport_1:= and friends won't be recognized by =org-mode= as anything\nspecial. Look at =org-export-exclude-tags= variable for more details.\n\n** Quote table of contents\n\nFor presentation purposes, you might want to put the table of contents in a\nquote block (i.e. =#+BEGIN_QUOTE= / =#+END_QUOTE=). In that case, GitHub, for\nexample, will add a vertical line to the left of the TOC that makes it distinct\nfrom the main text. To do this, just add a =:QUOTE:= tag to the TOC heading.\n\n** Shortcut for TOC tag\n\nIn your emacs' setup, you can bind a tag =:TOC:= to a binding =T=:\n\n#+BEGIN_SRC emacs-lisp\n  (add-to-list 'org-tag-alist '(\"TOC\" . ?T))\n#+END_SRC\n\nNow =C-c C-q T RET= and you are done putting the =:TOC:= entry.\n\n* Markdown support\n\nYou can also enable the mode in Markdown files and get pretty much the same\nfunctionality. The package will\n1. Look for '#'s instead of '*'s as heading markers.\n2. Expect the =:TOC:= tag to appear as comment, like, =\u003c!-- :TOC: --\u003e=\n3. Format the links and the quote block according to Markdown syntax\n\nExample:\n\n#+BEGIN_SRC markdown\n  # About\n  # Table of Contents                                    \u003c!-- :TOC: --\u003e\n  - [About](#about)\n  - [Installation](#installation)\n    - [via package.el](#via-packageel)\n    - [Manual](#manual)\n  - [Use](#use)\n  - [Example](#example)\n\n  # Installation\n  ## via package.el\n  ## Manual\n  # Use\n  # Example\n#+END_SRC\n\n* Different href styles\n\nCurrently, only 2 href styles are supported: =gh= and =org=. You can easily\ndefine your own styles. If you use the tag =:TOC_2_STYLE:= (=STYLE= being a\nstyle name), then the package will look for a function named\n=toc-org-hrefify-STYLE=.\n\nIt should accept a heading string and a hash table of previously generated\nhrefs. The table can be used to maintain href uniqueness (see\n=toc-org-hrefify-gh=, for example). Return value should be a href corresponding\nto that heading.\n\nE.g. for =org= style it makes links to be the same as their visible text:\n\n#+BEGIN_SRC emacs-lisp\n  (defun toc-org-hrefify-org (str \u0026optional hash)\n    \"Given a heading, transform it into a href using the org-mode\n  rules.\"\n    (toc-org-format-visible-link str))\n#+END_SRC\n\n* Example\n#+BEGIN_SRC org\n  * About\n  * Table of Contents                                           :TOC:\n  - [[#about][About]]\n  - [[#installation][Installation]]\n    - [[#via-packageel][via package.el]]\n    - [[#manual][Manual]]\n  - [[#use][Use]]\n  - [[#example][Example]]\n\n  * Installation\n  ** via package.el\n  ** Manual\n  * Use\n  * Example\n#+END_SRC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnosov1%2Ftoc-org","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnosov1%2Ftoc-org","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnosov1%2Ftoc-org/lists"}