{"id":13894713,"url":"https://github.com/zevlg/ellit-org.el","last_synced_at":"2026-03-11T19:15:00.715Z","repository":{"id":44898921,"uuid":"235521375","full_name":"zevlg/ellit-org.el","owner":"zevlg","description":"Emacs Lisp Literate programming tool","archived":false,"fork":false,"pushed_at":"2022-01-19T22:16:35.000Z","size":249,"stargazers_count":19,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-12T21:49:12.725Z","etag":null,"topics":["gnu-emacs"],"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/zevlg.png","metadata":{"files":{"readme":"README.org","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":"2020-01-22T07:30:41.000Z","updated_at":"2024-06-29T06:48:03.000Z","dependencies_parsed_at":"2022-09-16T03:41:06.518Z","dependency_job_id":null,"html_url":"https://github.com/zevlg/ellit-org.el","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zevlg/ellit-org.el","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevlg%2Fellit-org.el","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevlg%2Fellit-org.el/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevlg%2Fellit-org.el/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevlg%2Fellit-org.el/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zevlg","download_url":"https://codeload.github.com/zevlg/ellit-org.el/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevlg%2Fellit-org.el/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30395156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T18:46:22.935Z","status":"ssl_error","status_checked_at":"2026-03-11T18:46:17.045Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["gnu-emacs"],"created_at":"2024-08-06T18:01:43.213Z","updated_at":"2026-03-11T19:15:00.689Z","avatar_url":"https://github.com/zevlg.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"#+OPTIONS: timestamp:nil \\n:t\n#+TITLE: [[ellit-org-logo64.png]] ellit-org (v0.9)\n#+AUTHOR: Zajcev Evgeny\n#+startup: showall\n\n[[https://github.com/zevlg/ellit-org.el/actions][https://github.com/zevlg/ellit-org.el/workflows/CI/badge.svg]]\n\n#+begin_quote\nThis file is automatically generated from =ellit-org.el= by\n[[https://github.com/zevlg/ellit-org.el][GitHub#ellit-org.el]] tool.\nDo not edit manually.\n#+end_quote\n\nUltimate tool to document your Emacs Lisp project without much effort.\n\nGenerate documentation for your Emacs Lisp package by combining\n=.org= files and useful bits from comments in =.el= files.\n\nIdea is similar to https://github.com/tumashu/el2org\n\nHowever =ellit-org= implements more features, such as:\n- Easy to use comments extractor from =.el=, see [[#commenting-el-files][Commenting files]]\n- [[#combining-multiple-files][Combining multiple files]], =.org= or =.el=\n- GitHub friendly ~:CUSTOM_ID~ property generation for headings, so\n  exporting html to GitHub Pages from resulting =.org= is easy as\n  calling ~org-html-export-to-html~ function\n- [[#templates][Templating]]\n\n* Why?\n:PROPERTIES:\n:CUSTOM_ID: why\n:END:\n\nSeparate files for code and documentation is hard to get in sync.\nOnce changing something in source code files, you might change\ncomments as well and forget about documentation.  In other words\nhaving documentation in source code is easier to maintain for the\ndevelopers.\n\nAlso many things, useful for documentation, might be automatically\nextracted from source code.  Such as:\n- Keybindings\n- Customizable options\n- Docstrings for commands\n- etc\n\n* Using ellit-org in your project\n:PROPERTIES:\n:CUSTOM_ID: using-ellit-org-in-your-project\n:END:\n\nSample Makefile to generate user manual for the project:\n\n#+begin_src Makefile\n  EMACS=emacs -Q\n\n  manual.org: srcfile.el \u003clist-of-other-files-used-to-generate-manual\u003e\n       $(EMACS) -batch -f package-initialize -l ellit-org \\\n  \t\t --eval '(ellit-org-export \"srcfile.el\" \"manual.org\")'\n#+end_src\n\n** Projects that uses ellit-org\n:PROPERTIES:\n:CUSTOM_ID: projects-that-uses-ellit-org\n:END:\n\n- =ellit-org= itself, see [[https://github.com/zevlg/ellit-org.el/blob/master/Makefile][Makefile]]\n- [[https://github.com/zevlg/telega.el][telega.el]] uses =ellit-org= to generate its [[https://zevlg.github.io/telega.el/][Manual]], see its [[https://github.com/zevlg/telega.el/blob/master/docs/Makefile][Makefile]]\n- [[https://github.com/zevlg/grammarbot.el][grammarbot.el]], see its [[https://github.com/zevlg/grammarbot.el/blob/master/Makefile][Makefile]]\n\n* Commenting .el files\n:PROPERTIES:\n:CUSTOM_ID: commenting-el-files\n:END:\n\n1. Use ~;;; ellit-org: [LABEL]~ as trigger for ellit-org to start\n   processing following comments\n2. Processing stops on any non-commentary line\n3. When processing stops, newline is emmited to output\n\nHere is the example:\n#+begin_src emacs-lisp\n  ;;; ellit-org:\n  ;; * Heading1                        \u003c--- processing starts here\n  ;; This line is included into output\n  ;;\n  ;; This line also included into output\n  \t\t\t\t     \u003c--- processing stops here\n  ;; This line is NOT included into output\n  ;; * This line also NOT included\n\n  ;;; ellit-org:\n  ;; - However this line, is included  \u003c--- processing starts here\n  ;;\n  ;;    Since new processing is started, and it will stop only on\n  ;;    non-commentary line below\n  \t\t\t\t     \u003c--- processing stops here\n  ;; This line is *not* included\n#+end_src\n\n* Combining multiple files\n:PROPERTIES:\n:CUSTOM_ID: combining-multiple-files\n:END:\n\nMultiple =.org= and =.el= files might be combined forming final\nresult as single =.org= file.\n\n*TODO*: Describe labels purpose inside ellit-driven files\n\n*TODO*: Describe ~#+ELLIT-INCLUDE:~ directive, and its properties:\n- ~:eval-p~ to get include filename by evaluating sexp\n- ~:no-load~ do not load corresponding =.el= file\n- ~:label~ To include only given label from =.el= or =.org= file\n- ~:heading~ To include only given heading\n\n* Templates\n:PROPERTIES:\n:CUSTOM_ID: templates\n:END:\n\nellit-org relies on Org mode's macro system by adding some useful\nmacroses.  See https://orgmode.org/manual/Macro-replacement.html\n\nMacro replacement is done *after* processing comments, so make\nsure your macroses are in processed part of the comments.\n\nTemplates syntax:\n#+begin_example\n  {{{macro_name(arguments)}}}\n#+end_example\n\n~ARGUMENTS~ are optional string supplied to function which does\nprocessing for ~MACRO_NAME~.\n\nSupported templates:\n\n- eval(~SEXP~ [, ~AS-STRING~ ]) :: \n     Insert results of the ~SEXP~ evaluation.\n     If ~AS-STRING~ is non-nil then use \"%s\" instead of \"%S\" for\n     formatting ~SEXP~.\n\n- as-is(~STRING~) :: \n     Insert ~STRING~ as is.\n\n     ~as-is(STRING)~ filter is equivalent to ~eval(\"STRING\", t)~\n\n- ellit-filename([ ~VERBATIM~ ]) :: \n     Insert currently processing filename.\n     If ~VERBATIM~ is specified, then outline filename with verbatim markup.\n\n- kbd(~KEY~) :: \n     Insert HTML \u003ckbd\u003e tag with ~KEY~ contents.\n\n- where-is(~COMMAND~ [, ~KEYMAP~ [, ~MENU-ITEMS~ ]]) :: \n     Insert list of keys that calls ~COMMAND~.\n     ~KEYMAP~ is keymap where to lookup for ~COMMAND~.  By default\n     ~global-map~ is considered.\n\n     If ~MENU-ITEMS-P~ is specified, then also insert commands inside\n     menu-items.\n\n- vardoc1(~VARIABLE~) :: \n     Insert first line from docstring for the ~VARIABLE~.\n\n- vardoc(~VARIABLE~ [, ~INDENT-LEVEL~ ]) :: \n     Insert full docstring for the ~VARIABLE~.\n\n- fundoc1(~FUNCTION~) :: \n     Insert first line from docstring for the ~FUNCTION~.\n\n- fundoc(~FUNCTION~ [, ~INDENT-LEVEL~ ]) :: \n     Insert full docstring for the ~FUNCTION~.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevlg%2Fellit-org.el","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzevlg%2Fellit-org.el","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevlg%2Fellit-org.el/lists"}