{"id":22197561,"url":"https://github.com/functionhaus/arcdown","last_synced_at":"2025-07-04T16:32:26.101Z","repository":{"id":57478963,"uuid":"166256294","full_name":"functionhaus/arcdown","owner":"functionhaus","description":"A parsing library for articles written in Arcdown (.ad) format.","archived":false,"fork":false,"pushed_at":"2019-01-20T19:59:01.000Z","size":339,"stargazers_count":7,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-01T09:41:14.705Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","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/functionhaus.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":"2019-01-17T16:16:43.000Z","updated_at":"2020-03-08T06:40:54.000Z","dependencies_parsed_at":"2022-09-18T05:44:55.511Z","dependency_job_id":null,"html_url":"https://github.com/functionhaus/arcdown","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/functionhaus/arcdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/functionhaus%2Farcdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/functionhaus%2Farcdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/functionhaus%2Farcdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/functionhaus%2Farcdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/functionhaus","download_url":"https://codeload.github.com/functionhaus/arcdown/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/functionhaus%2Farcdown/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263577242,"owners_count":23483130,"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":[],"created_at":"2024-12-02T14:19:55.646Z","updated_at":"2025-07-04T16:32:26.083Z","avatar_url":"https://github.com/functionhaus.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arcdown\n\n[![CircleCI](https://circleci.com/gh/functionhaus/arcdown.svg?style=svg)](https://circleci.com/gh/functionhaus/arcdown)\n\nArcdown is a parsing library for articles written in Arcdown (.ad) format.\n\nIt is written in pure Elixir/Erlang with no additional dependencies when being\nused in production.\n\n# What is Arcdown (.ad) format?\n\nArcdown (.ad) format is a lightweight file format for writing full-featured\ncontent and articles as plain text in order to easily parse them as rich\nobjects.\n\nThe objective of this format is to allow the author to write full articles\nin plain text in order to easily parse them into rich objects in whatever\nlanguage you're using.\n\nArcdown supports the following features:\n\n* title\n* url slug\n* author name and email\n* topics and sub-topics\n* tags\n* article summary\n* article content\n\nHere is an example article written in *Arcdown (.ad)* format:\n\n```\nThe Day the Earth Stood Still \u003cthe-day-the-earth-stood-still\u003e\nby Julian Blaustein \u003cjulian@blaustein.com\u003e\n\nFiled under: Films \u003e Sci-Fi \u003e Classic\n\nCreated @ 10:24pm on 1/20/2019\nPublished @ 10:20pm on 1/20/2019\n\n* Sci-Fi\n* Horror\n* Thrillers\n* Aliens\n\nSummary:\nA sci-fi classic about a flying saucer landing in Washington, D.C.\n\n---\n\nThe Day the Earth Stood Still (a.k.a. Farewell to the Master and Journey to the\nWorld) is a 1951 American black-and-white science fiction film from 20th Century\nFox, produced by Julian Blaustein and directed by Robert Wise.\n```\n\nArcdown doesn't presume that you want to parse the Article content/body in any\nparticular way in order to give you as much flexibility as possible in its\nusage. It's simple enough, however, to simply write the Article content as\nMarkdown (.md) and parse that later with a library like\n[Earmark](https://github.com/pragdave/earmark).\n\nIt's suggested that Arcdown files with the content body written in Markdown use\nthe *.md.ad* file extension to remain conventionally consistent.\n\nAdditional content parsing options may be included in the future, but for now\nthe goal is to remain as content-agnostic as possible in order to give users the\nchoice of how format and write their own articles.\n\n## Installation\n\nThe package can be installed by adding `arcdown` to your list of\ndependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:arcdown, \"~\u003e 0.1\"}\n  ]\nend\n```\n\nArcdown has no dependencies other than ex_doc which is only included in the `docs`\ncontext.\n\n## Usage\n\nParsing Arcdown text is easy thanks to a couple of helpers in the top-level\nArcdown module. The default interface permits parsing Arcdown text either\ndirectly from a file, like this:\n\n```elixir\n{:ok, parsed} = Arcdown.parse_file \"earth_stood_still.ad\"\n```\n\nOr just by parsing the entire text from a string, like this:\n\n```elixir\narticle_text = \"\"\"\nThe Day the Earth Stood Still \u003cthe-day-the-earth-stood-still\u003e\nby Julian Blaustein \u003cjulian@blaustein.com\u003e\n\nFiled under: Films \u003e Sci-Fi \u003e Classic\n\nCreated @ 10:24pm on 1/20/2019\nPublished @ 4:30am on 4/2/2019\n\n* Sci-Fi\n* Horror\n* Thrillers\n* Aliens\n\nSummary:\nA sci-fi classic about a flying saucer landing in Washington, D.C.\n\n---\n\nThe Day the Earth Stood Still (a.k.a. Farewell to the Master and Journey to the\nWorld) is a 1951 American black-and-white science fiction film from 20th Century\nFox, produced by Julian Blaustein and directed by Robert Wise.\n\"\"\"\n\n{:ok, parsed} = Arcdown.parse article_text\n```\n\nIn both instances, the parser will return a tuple in the format of\n`{:ok, %Arcdown.Article{}}`. The Article struct will contain all of its data\nattributes fully parsed and formatted. Presuming that the text in both examples\nabove match the string-parsing example, the resulting struct would look like\nthis:\n\n```elixir\n%Arcdown.Article{\n  author: \"Julian Blaustein\",\n  content: \"The Day the Earth Stood Still (a.k.a. Farewell to the Master and Journey to the\\nWorld) is a 1951 American black-and-white science fiction film from 20th Century\\nFox, produced by Julian Blaustein and directed by Robert Wise.\\n\",\n  created_at: #DateTime\u003c2019-01-20 22:24:00Z\u003e,\n  email: \"julian@blaustein.com\",\n  published_at: #DateTime\u003c2019-04-02 04:30:00Z\u003e,\n  slug: \"the-day-the-earth-stood-still\",\n  summary: \"A sci-fi classic about a flying saucer landing in Washington, D.C.\",\n  tags: [:sci_fi, :horror, :thrillers, :aliens],\n  title: \"The Day the Earth Stood Still\",\n  topics: [\"Films\", \"Sci-Fi\", \"Classic\"]\n}\n```\n\n### Arcdown Formatting\n\nBecause arcdown (.ad) files are parsed entirely with robust regular expressions,\nformatting must match the above example exactly.\n\nHowever not all of the above elements have to be included in an arcdown file.\nIn fact it's perfectly acceptable to parse an empty file. Arcdown will just\nreturn an empty `%Arcdown.Article{}` struct.\n\nThere are some situations in which extraneous whitespace `\\s` and newline `\\n`\ncharacters will be trimmed and ignored, but for the mostpart Arcdown wants you\nto follow its format as close to the letter as possible in order to not have to\nbloat its parsing logic with attempts to discern formatting errors.\n\n### The Arcdown Header\n\nYou're welcome to just parse header information, for example, if you haven't\nwritten your article yet but know how you want to title and categorize it.\nHere is an example of a complete header:\n\n```\nThe Day the Earth Stood Still \u003cthe-day-the-earth-stood-still\u003e\nby Julian Blaustein \u003cjulian@blaustein.com\u003e\n\nFiled under: Films \u003e Sci-Fi \u003e Classic\n\nCreated @ 10:24pm on 1/20/2019\nPublished @ 10:20pm on 1/20/2019\n\n* Sci-Fi\n* Horror\n* Thrillers\n* Aliens\n\nSummary:\nA sci-fi classic about a flying saucer landing in Washington, D.C.\n```\n\nNotice how there is no three-hyphen *content divider* ending the header text\nhere. The divider has semantic importance in parsing Arcdown files, and always\ndenotes the beginning of a content section.\n\nIf your article contains no content yet, exclude the trailing divider.\n\n### Arcdown Content\n\nThe *Content* portion of an Arcdown file always begins with the hyphen divider\n`---` followed by two newline characters.\n\nThis is a valid Arcdown file in which the parser will simply extract the content\nbody and ignore any header parsing in the absence of header data:\n\n```\n---\n\nThe Day the Earth Stood Still (a.k.a. Farewell to the Master and Journey to the\nWorld) is a 1951 American black-and-white science fiction film from 20th Century\nFox, produced by Julian Blaustein and directed by Robert Wise.\n```\n\nOmitting the hyphen divider `---` element will suggest to the parser that this\nis actually the title of the article rather than the content. As such, the\ndivider must begin the parsed string, followed by two newlines, like this:\n`---\\n\\nContent goes here.`\n\n## Availability\n\nThis library is currently published at for use with the public hex.pm\nrepository at https://hex.pm/packages/arcdown.\n\nSource code is available at the [FunctionHaus Github Organization](\nhttps://github.com/functionhaus) at\nhttps://github.com/functionhaus/arcdown.\n\n\n## License\n\nArcdown source code is released under Apache 2 License.\nCheck LICENSE file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunctionhaus%2Farcdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunctionhaus%2Farcdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunctionhaus%2Farcdown/lists"}