{"id":20027687,"url":"https://github.com/fabriziomusacchio/devonthink_generate_markdown_toc","last_synced_at":"2025-05-05T03:31:46.449Z","repository":{"id":41143505,"uuid":"508464333","full_name":"FabrizioMusacchio/DEVONthink_Generate_Markdown_TOC","owner":"FabrizioMusacchio","description":"Generates a table of contents and Back-to-top links in DEVONthink's Markdown documents.","archived":false,"fork":false,"pushed_at":"2022-07-22T16:21:51.000Z","size":3500,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-08T16:02:21.061Z","etag":null,"topics":["applescript","devonthink","markdown","python","table-of-contents","table-of-contents-generator","toc","toc-generator"],"latest_commit_sha":null,"homepage":"https://www.fabriziomusacchio.com/blog/2022-07-08-devonthink_toc/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FabrizioMusacchio.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}},"created_at":"2022-06-28T21:47:37.000Z","updated_at":"2025-01-12T19:31:56.000Z","dependencies_parsed_at":"2022-07-13T19:30:35.774Z","dependency_job_id":null,"html_url":"https://github.com/FabrizioMusacchio/DEVONthink_Generate_Markdown_TOC","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabrizioMusacchio%2FDEVONthink_Generate_Markdown_TOC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabrizioMusacchio%2FDEVONthink_Generate_Markdown_TOC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabrizioMusacchio%2FDEVONthink_Generate_Markdown_TOC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FabrizioMusacchio%2FDEVONthink_Generate_Markdown_TOC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FabrizioMusacchio","download_url":"https://codeload.github.com/FabrizioMusacchio/DEVONthink_Generate_Markdown_TOC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252434784,"owners_count":21747289,"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":["applescript","devonthink","markdown","python","table-of-contents","table-of-contents-generator","toc","toc-generator"],"created_at":"2024-11-13T09:11:24.950Z","updated_at":"2025-05-05T03:31:45.687Z","avatar_url":"https://github.com/FabrizioMusacchio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DEVONthink Markdown TOC generator\n\nThis AppleScript generates a table of contents (TOC) and adds a floating back-to-top button in DEVONthink's Markdown documents.\n\n\u003cp align=\"center\"  style=\"text-align: center;\"\u003e\n\u003ca href=\"Screenshots/Screenshot_preview_new.png\"\u003e\u003cimg src=\"Screenshots/Screenshot_preview_new.png\" style=\"width: 90%;\"\u003e\u003c/a\u003e\n\u003ca href=\"Screenshots/Screenshot_editview_new.png\"\u003e\u003cimg src=\"Screenshots/Screenshot_editview_new.png\" style=\"width: 90%;\"\u003e\u003c/a\u003e\n\nThe generated TOC and the floating Back-to-top button in DEVONthink's Markdown preview (top) and edit (bottom) view. \n\u003c/p\u003e\n\n## How to install\nDownload the two AppleScript and Python files:\n\n* TOC generate.applescript\n* TOC remove.applescript\n* generate_toc.py\n* remove_toc.py\n\nPlace the AppleScript files into DEVONthink's script folder.\n\n\u003cp align=\"center\" style=\"text-align: center;\"\u003e\n\u003ca href=\"Screenshots/Screenshot_DEVONthink_script_folder.png\"\u003e\u003cimg src=\"Screenshots/Screenshot_DEVONthink_script_folder.png\" style=\"width: 100%;\"\u003e\u003c/a\u003e\n\nOpen DEVONthink's script folder via DEVONthink's script menu.\n\u003c/p\u003e \n\nPlace the Python scripts into a folder of your choice. The path to the folder containing the Python scripts must be specified in the `MyPythonScriptPath` variable within the AppleScripts. \n\nThe AppleScripts rely on these Python scripts, which work for both Python 2 and 3. On macOS \u003c12.3, set the `LocalPython` variable in the AppleScript to \"/usr/bin/python\". For higher macOS versions, install Python (e.g., via [Anaconda.com](https://www.anaconda.com) or [python.org](https://www.python.org/downloads/)), find out the path of the Python installation (open a terminal and type \"which python\") and set `LocalPython` to the given result. \n\n\n\nTo make the floating Back-to-toc button work, please add the followong CSS commands to your Markdown style sheet file:\n\n```css\n@media screen and (prefers-reduced-motion: no-preference) {\n  html {\n    scroll-behavior: smooth;\n  }\n}\n\n.top-link {\n  transition:       all .25s ease-in-out;\n  position:         fixed;\n  bottom:           0;\n  right:            0;\n  display:          inline-flex;\n  color:            #000000;\n\n  cursor:           pointer;\n  align-items:      center;\n  justify-content:  center;\n  margin:           0 2em 2em 0;\n  border-radius:    50%;\n  padding:          .25em;\n  width:            1em;\n  height:           1em;\n  background-color: #F8F8F8;\n}\n```\n\nThe CSS commands for the TOC layout are:\n\n```css\n.TOC {\n    background:     #f4f5f8 none repeat scroll 0 0; //f3f6f6\n    border:         0px solid #aaa;\n    border-radius:  10px;\n    display:        table;\n    font-size:      95%;\n    margin-bottom:  1em;\n    padding-left:   2px;\n    padding-top:    2px;\n    padding-bottom: 2px;\n    padding-right:  2px;\n    width:          100%;\n}\n\n.TOC li, .TOC ul, .TOC ul li{\n    list-style:     decimal;\n}\n\n/*Uncomment to add a title to your TOC:*/\n/*.TOC:before {\n    content:        \"Table of Contents\";\n    font-weight:    bold;\n    font-size:      1.1em;\n    color:          #3973ad;\n    padding-left:   1em;\n    margin-bottom: -1em;\n    line-height:    3em;\n}*/\n```\n\nYou can also find my full CSS file [here](https://github.com/FabrizioMusacchio/GitHub_Flavor_Markdown_CSS).\n\nTo make the floating Back-to-toc button work in DEVONthink To Go (DTTG) as well, please [add the CSS commands from above into the CSS field of DTTG](https://github.com/FabrizioMusacchio/GitHub_Flavor_Markdown_CSS#floating-back-to-top-button-in-devonthink-to-go).\n\n\n## How the script works\nThe AppleScript hands-over the document's content to the Python script, which scans for all lines starting with a `#`, collects the heading texts and adds a label at the end of each headline (e.g., `## Section 1 [h0]`). The labels – not visible in the preview mode – are required for a simple but unambiguous linking to the headlines and are automatically updated with each run of the script. In the [version with Back-to-toc links](#version-with-back-to-toc-links), a Back-to-toc link is placed over each headline, which links to the TOC. \n\nThe script also scans for an existing TOC. If available, that TOC is updated and its previous position in the document is retained. I.e., after the first run of the script, a TOC section (`\u003c!-- TOC START --\u003e...\u003c!-- TOC END --\u003e`) is inserted right after the first line of the document. You can freely move that section within the document.\n\nIn the Python script, you can define the TOC-level to be considered by adjusting the `toc_level` variable:\n\n```\ntoc_level defines at which toc-level to start, e.g.:\n  2 - only account for headings h2 (##) and higher; requires that\n      the first occuring heading is h2 (except the document\n      heading in line 0 (headline_index))\n  1 - account for headings h1 (#) and higher; requires that a\n      the first occuring heading is h1 (except the document\n      heading in line 0 (headline_index))\n```\n\nBy default, the script ignores the first line of the document, so that the document's title will not be part of the TOC. \n\nThe script respects a so-called reference\nlinks section (`\u003c!-- LINKS START --\u003e...\u003c!-- LINKS END --\u003e?`, if available). This section is the result of another AppleScript I apply for handling Markdown reference links.\n\nWhen the Python script is done, the original content including the TOC and all other additions is handed-over back to the AppleScript, which replaces the document's current content with the updated one.\n\nThe \"TOC remove\" script removes the generated TOC, the added headline labels and the Back-to-toc links (if available).\n\n## Version with Back-to-toc links\nThe version \n\n* TOC generate with btt-links.applescript\n\ndiffers from the one above in such a away, that it adds Back-to-toc links above each headline instead of the floating back-to-toc button. It also does not require any additional CSS commands. \n\n\u003cp align=\"center\" style=\"text-align: center;\"\u003e\n\u003ca href=\"Screenshots/Screenshot_preview.png\"\u003e\u003cimg src=\"Screenshots/Screenshot_preview.png\" style=\"width: 90%;\"\u003e\u003c/a\u003e\n\u003ca href=\"Screenshots/Screenshot_editview.png\"\u003e\u003cimg src=\"Screenshots/Screenshot_editview.png\" style=\"width: 90%;\"\u003e\u003c/a\u003e\n\nThe generated TOC with Back-to-toc links in DEVONthink's Markdown preview (top) and edit (bottom). \n\u003c/p\u003e\n\n\n\n## Use at your own risk\nI checked all scripts for various possible formatting within a Markdown document and I tried to make them as failure-resistant as possible. Nevertheless, the scripts replace your document's content with an actually new version of the content, which contains the additions mentioned above. In extreme cases, formatting that have not yet been taken into account can cause the scripts to delete parts of the content or even the entire content. **Therefore, please backup your files before you apply the scripts and first try them out with some Markdown files, that contain some formatting that you usually apply to your documents**. Please report any bug in the issue section of this repository.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziomusacchio%2Fdevonthink_generate_markdown_toc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabriziomusacchio%2Fdevonthink_generate_markdown_toc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziomusacchio%2Fdevonthink_generate_markdown_toc/lists"}