{"id":13576654,"url":"https://github.com/PowerShell/platyPS","last_synced_at":"2025-04-05T08:32:42.014Z","repository":{"id":29739781,"uuid":"33283220","full_name":"PowerShell/platyPS","owner":"PowerShell","description":"Write PowerShell External Help in Markdown","archived":false,"fork":false,"pushed_at":"2025-03-12T18:42:26.000Z","size":5672,"stargazers_count":800,"open_issues_count":56,"forks_count":158,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-03-30T14:04:12.900Z","etag":null,"topics":["powershell"],"latest_commit_sha":null,"homepage":"","language":"C#","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/PowerShell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-02T01:47:32.000Z","updated_at":"2025-03-28T10:50:19.000Z","dependencies_parsed_at":"2023-02-10T22:55:11.504Z","dependency_job_id":"5be67479-bfff-4b26-9e24-4de5faee4562","html_url":"https://github.com/PowerShell/platyPS","commit_stats":{"total_commits":705,"total_committers":48,"mean_commits":14.6875,"dds":0.5347517730496454,"last_synced_commit":"f9fa12821b6dbacdd16cc486b77787cdc51242fa"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FplatyPS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FplatyPS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FplatyPS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FplatyPS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PowerShell","download_url":"https://codeload.github.com/PowerShell/platyPS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247311896,"owners_count":20918339,"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":["powershell"],"created_at":"2024-08-01T15:01:12.494Z","updated_at":"2025-04-05T08:32:41.512Z","avatar_url":"https://github.com/PowerShell.png","language":"C#","readme":"# PlatyPS\n\nPlatyPS provides a way to:\n\n- Write PowerShell External Help in Markdown\n- Generate markdown help\n- Keep markdown help up-to-date with your code\n- Create updateable help files\n\nMarkdown help docs can be generated from old external help files (also known as MAML-xml help), the\ncommand objects (reflection), or both.\n\n## Why?\n\nTraditionally PowerShell external help files have been authored by hand or using complex tool chains\nand rendered as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common\ntools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is\nprovided as a solution for allow documenting PowerShell help in any editor or tool that supports\nMarkdown.\n\nAn additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios\n(e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have\ndocumentation abstracted away from the codebase. PlatyPS doesn't need source access to generate\ndocumentation.\n\nMarkdown is designed to be human-readable, without rendering. This makes writing and editing easy\nand efficient. Many editors support it, including [Visual Studio Code][04], and many tools and\ncollaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely.\n\n## Common setups\n\nThere are 2 common setups that are used:\n\n1. Use markdown as the source of truth and remove other types of help.\n1. Keep comment based help as the source of truth and periodically generate markdown for web-site\n   publishing.\n\nThey both have advantages and use-cases, you should decide what's right for you. There is slight\npreference toward number 1 (markdown as the source).\n\n## Quick start\n\n- Install platyPS module from the [PowerShell Gallery][07]:\n\n```powershell\nInstall-Module -Name platyPS -Scope CurrentUser\nImport-Module platyPS\n```\n\n- Create initial Markdown help for `MyAwesomeModule` module:\n\n```powershell\n# you should have module imported in the session\nImport-Module MyAwesomeModule\nNew-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\\docs\n```\n\n- Edit markdown files in `.\\docs` folder and populate `{{ ... }}` placeholders with missed help content.\n- Create external help from markdown help\n\n  ```powershell\n  New-ExternalHelp .\\docs -OutputPath en-US\\\n  ```\n\n  **Congratulations**, your help is now in markdown!\n\n- Now, if your module code changes, you can easily update your markdown help with\n\n  ```powershell\n  # re-import your module with latest changes\n  Import-Module MyAwesomeModule -Force\n  Update-MarkdownHelp .\\docs\n  ```\n\n### PlatyPS markdown schema\n\nUnfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a\n**particular way**. We have defined a [**schema**][03] to determine how parameters are described,\nwhere scripts examples are shown, and so on.\n\nThe schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell.\n\nIf you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and\n`Update-MarkdownHelp`. You would not be able to generate extrenal help or update your markdown.\n\nIt may be fine for some scenarios, i.e. you want to have online-only version of markdown.\n\n## [Usage][06]\n\nSupported scenarios:\n\n- Create Markdown\n  - Using existing external help files (MAML schema, XML).\n  - Using reflection\n  - Using reflection and existing internal external help files.\n  - For a single cmdlet\n  - For an entire module\n- Update existing Markdown through reflection.\n- Create a module page `\u003cModuleName\u003e.md` with summary. It will also allow you to create updatable\n  help cab.\n- Retrieve markdown metadata from markdown file.\n- Create external help xml files (MAML) from platyPS Markdown.\n- Create external help file cab\n- Preview help from generated maml file.\n\n## Remoting\n\nPlatyPS supports working with [Import-PSSession][05] aka implicit remoting. Just pass\n`-Session $Session` parameter to the platyPS cmdlets and it will do the rest.\n\n## Build\n\nFor information about building from sources and contributing see [contributing guidelines][02].\n\n## Code of Conduct\n\nPlease see our [Code of Conduct][01] before participating in this project.\n\n## Security Policy\n\nFor any security issues, please see our [Security Policy][08].\n\n\u003c!-- link references --\u003e\n[01]: CODE_OF_CONDUCT.md\n[02]: docs/developer/platyPS/CONTRIBUTING.md\n[03]: docs/developer/platyPS/platyPS.schema.md\n[04]: https://code.visualstudio.com/\n[05]: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/import-pssession\n[06]: https://learn.microsoft.com/powershell/module/platyps/\n[07]: https://www.powershellgallery.com/packages/platyPS\n[08]: SECURITY.md\n","funding_links":[],"categories":["powershell","C#","C# #","C\\#","Documentation Helper","Powershell ##"],"sub_categories":["Modules ###"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPowerShell%2FplatyPS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPowerShell%2FplatyPS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPowerShell%2FplatyPS/lists"}