{"id":15059687,"url":"https://github.com/dmy/elm-doc-preview","last_synced_at":"2025-05-16T08:05:32.269Z","repository":{"id":33762703,"uuid":"149329690","full_name":"dmy/elm-doc-preview","owner":"dmy","description":"Elm offline documentation previewer","archived":false,"fork":false,"pushed_at":"2024-12-12T18:07:38.000Z","size":1431,"stargazers_count":129,"open_issues_count":5,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-14T17:27:01.988Z","etag":null,"topics":["application","doc","documentation","elm","package","preview","viewer"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/elm-doc-preview","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-18T17:49:28.000Z","updated_at":"2025-05-12T19:46:04.000Z","dependencies_parsed_at":"2023-01-15T02:23:25.977Z","dependency_job_id":null,"html_url":"https://github.com/dmy/elm-doc-preview","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmy%2Felm-doc-preview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmy%2Felm-doc-preview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmy%2Felm-doc-preview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmy%2Felm-doc-preview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmy","download_url":"https://codeload.github.com/dmy/elm-doc-preview/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"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":["application","doc","documentation","elm","package","preview","viewer"],"created_at":"2024-09-24T22:46:39.985Z","updated_at":"2025-05-16T08:05:27.260Z","avatar_url":"https://github.com/dmy.png","language":"Elm","funding_links":[],"categories":["Other tools"],"sub_categories":["Unmaintained"],"readme":"# elm-doc-preview\n\nThis is an Elm 0.19 **offline** documentation previewer for **packages**,\n**applications**, their **dependencies** and **all cached packages**.\n\nIt aims at rendering documentation exactly like the\n[official package website](https://package.elm-lang.org) to avoid\nany surprise when releasing a package.\n\n# Features\n\n- **Packages** and **Applications** support with **documentation hot reloading**\n- **Offline cached packages documentation server**\n- Source and documentation compilation errors display\n- Online documentation sharing for reviews (using the\n [online version](#online-version))\n\n![elm-doc-preview](https://github.com/dmy/elm-doc-preview/raw/d3d19a2/screenshots/elm-doc-preview.png)\n\n# Installation\n\n```sh\n$ npm install -g elm-doc-preview\n```\n\n`npm` may warn about missing peer dependencies:\n```\nnpm WARN ws@7.2.3 requires a peer of bufferutil@^4.0.1 but none is installed. You must install peer dependencies yourself.\nnpm WARN ws@7.2.3 requires a peer of utf-8-validate@^5.0.2 but none is installed. You must install peer dependencies yourself.\n```\nThey are optional, provide marginal websockets optimizations for `elm-doc-preview` use case, and can be ignored.\n# Synopsis\n\n```text\nUsage: edp|elm-doc-preview [options] [path_to_package_or_application]\n\nOptions:\n  -V, --version             output the version number\n  -a, --address \u003caddress\u003e   the server listen address (default: \"127.0.0.1\")\n  -b, --no-browser          do not open in browser when server starts\n  -d, --debug               enable debug (display watched files and keep temporary files)\n  -o, --output \u003cdocs.json\u003e  generate docs and exit with status code (/dev/null supported)\n  -p, --port \u003cport\u003e         the server listen port (default: 8000)\n  -r, --no-reload           disable hot reloading\n  -h, --help                display help for command\n\n\nEnvironment variables:\n  ELM_HOME           Elm home directory (cache)\n```\n\nFor example, from the directory where your project `elm.json` is:\n\n```sh\n$ elm-doc-preview\n```\n\nor\n\n```sh\n$ edp\n```\n\nor from anywhere:\n\n```sh\n$ elm-doc-preview path/to/package_or_application\n```\nWhen no package or application is found, `elm-doc-preview` will just run as an\noffline documentation server for local cached packages.\n\n# Applications support\nApplication documentation is\n[not yet supported by Elm](https://github.com/elm/compiler/issues/1835#issuecomment-440080525),\nso `elm-doc-preview` will generate a package from the application with the same\nmodules and build the documentation from it. There are two consequences:\n1. You have to define an `elm-application.json` file to list the application\ndocumented modules (**exposed-modules**) and to customize the application\n**name**, **summary** or **version** that are included in the documentation.\n2. The application ports will be stubbed with fake versions as ports are\nforbidden in packages. This means that ports will appear as normal functions in\nthe documentation. Also currently, this requires ports declarations to be on\none line, if this is an issue for you, please\n[open an issue](https://github.com/dmy/elm-doc-preview/issues).\n\nWithout an `elm-application.json` file, `elm-doc-preview` will show an\napplication as `my/application 1.0.0` and will report an error about\nmissing `exposed-modules` unless some are eventually found in forked or\nlocal packages included in the application `source-directories`.\n\n**To configure the application, add an `elm-application.json` file with at least\nan `exposed-modules` value.**\n\nFor example, here is the\n[elm-application.json](https://github.com/dmy/elm-doc-preview/blob/master/elm-application.json)\nfile for the `elm-doc-preview` Elm application followed by a description of\neach field:\n\n`elm-application.json`:\n```elm-application.json\n{\n    \"name\": \"dmy/elm-doc-preview\",\n    \"summary\": \"Offline documentation previewer\",\n    \"version\": \"6.0.1\",\n    \"exposed-modules\": [\n        \"Href\",\n        \"Session\",\n        \"Page.Docs.Block\",\n        \"Page.Search\",\n        \"Page.Diff\",\n        \"Page.Problem\",\n        \"Page.Docs\",\n        \"Page.Search.Entry\",\n        \"Release\",\n        \"Utils.Spinner\",\n        \"Utils.OneOrMore\",\n        \"Utils.Logo\",\n        \"Utils.Error\",\n        \"Utils.Markdown\",\n        \"Main\",\n        \"Skeleton\"\n    ]\n}\n```\n#### **\"name\"**\nIt should use the same `author/project` format than packages, but the\nrepository does not have to exist on GitHub.\n\nThe default name is `my/application`.\n\n#### **\"summary\"**\nA short summary for the application in less than 80 characters.\n\nThe default summary is \"Elm application\".\n\n#### **\"version\"**\nA version using `MAJOR.MINOR.PATCH` format.\n\nThe default version is \"1.0.0\".\n\n#### **\"exposed-modules\"**\nThe modules to include in the documentation.\nAll exposed symbols inside these modules must be documented or the\ndocumentation build will fail.\n\nPort modules will be shown as normal modules.\n\nExposed modules contain by default those found in forked and local\npackages (see next section). Setting the field does not remove those\nmodules from the list.\n\n# Forked and local packages in applications\n`elm-doc-preview` will automatically exposes documentation for forked or local\npackages modules if their are exposed in an `elm.json` file located in the\ndirectory above the one declared in `source-directories`.\n\nTypically, to import a forked package and keep its documentation, just clone it\nin the application directory, and add the forked packages `src` sub-directory\nin `elm.json` `source-directories`.\n\n\n# Online version\n\nThere is also an online version supporting documentations loading from github\nto share them for online reviews:\n\nhttps://elm-doc-preview.netlify.app\n\nIt does not support hot-reloading or dependencies documentation though.\n\n# API\n```javascript\nimport DocServer from \"elm-doc-preview\";\nconst server = new DocServer();\nserver.listen();\n```\n\nor with custom options:\n\n```javascript\nimport DocServer from \"elm-doc-preview\";\n\n// constructor(options) {\n//   const {\n//     debug = false,\n//     dir = \".\",\n//     port = 8000,\n//     browser = true,\n//     reload = true\n//   } = options || {};\n//   ...\nconst server = new DocServer({ port: 9000, browser: false });\n\nserver.listen();\n```\n\n# FAQ\n\n## Is elm-doc-preview secure enough to publicly host documentation?\n`elm-doc-preview` is a development tool and is not designed to be\nexposed on internet. As such, no effort at all has been made to secure it\nand it most likely contains severe vulnerabilities. If you want to\npublicly share some documentation, use the [online version](#online-version) or maybe host\nstatic web pages of the documentation (see below).\n\n## How to generate static web pages of the documentation\nThis is not supported by `elm-doc-preview`, you could use [ento/elm-doc](https://github.com/ento/elm-doc) instead.\n\n\n## Why adding elm-application.json instead of using elm.json?\nExtending `elm.json` would not be convenient because `elm install`\nwill remove any unexpected field from it when run, and all the additional\nfields used by `elm-doc-preview` are currently unexpected for an application,\neven if they are valid for a package.\n\n## Why my forked/local/vendored packages modules are not automatically documented?\nThey are automatically added in the documentation if you kept the package\n`elm.json` file in the directory above the package `src` one.\n\n# Credits\n\n- Documentation rendering from [package.elm-lang.org](https://github.com/elm/package.elm-lang.org) by Evan Czaplicki.\n- Markdown rendering from [Marked.js](https://github.com/markedjs/marked) by Christopher Jeffrey.\n- Code highlighting from [highlight.js](https://github.com/highlightjs/highlight.js) by Ivan Sagalaev.\n- Code highlighting theme from [Solarized](ethanschoonover.com/solarized) by Jeremy Hull.\n- CSS spinner from [SpinKit](https://github.com/tobiasahlin/SpinKit) by Tobias Ahlin.\n- [Source Sans Pro](https://github.com/adobe-fonts/source-sans-pro) and\n  [Source Code Pro](https://github.com/adobe-fonts/source-code-pro) fonts by Paul D. Hunt.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmy%2Felm-doc-preview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmy%2Felm-doc-preview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmy%2Felm-doc-preview/lists"}