{"id":18090848,"url":"https://github.com/klml/proserial","last_synced_at":"2026-03-07T00:31:09.191Z","repository":{"id":139146202,"uuid":"56346080","full_name":"klml/proserial","owner":"klml","description":"A format to include structured data into prose. Use markdown for text and optional yaml below for data.","archived":false,"fork":false,"pushed_at":"2025-03-09T09:41:02.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-06T02:35:41.209Z","etag":null,"topics":["standard","static-site-generator"],"latest_commit_sha":null,"homepage":"","language":null,"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/klml.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-15T19:52:57.000Z","updated_at":"2025-03-09T09:41:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"16488c07-57db-45c0-a842-6b21b28fc3b2","html_url":"https://github.com/klml/proserial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/klml/proserial","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klml%2Fproserial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klml%2Fproserial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klml%2Fproserial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klml%2Fproserial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/klml","download_url":"https://codeload.github.com/klml/proserial/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klml%2Fproserial/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30204154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["standard","static-site-generator"],"created_at":"2024-10-31T18:08:08.418Z","updated_at":"2026-03-07T00:31:09.174Z","avatar_url":"https://github.com/klml.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# PROSErial\n\n\u003e moved to https://codeberg.org/klml/proserial  \n\u003e under construction\n\nMost [staticsitegenerators](https://staticsitegenerators.net/) use plain file to store their content in a mix from prose and structure.\n[Front Matter](https://github.com/jxson/front-matter) is widely used by several other systems, like [Jekyll](https://jekyllrb.com/docs/frontmatter/) or [HUGO](https://gohugo.io/content-management/front-matter/).\n\nThere are some confusing disadvantages for \"normal\" users:\n\n* it is __mandatory__, if you just want to write text, users will stumble over the YAML front matter block\n* [files must __begin__ with YAML Front Matter.](https://jekyllrb.com/docs/posts/) \n\n## form\n\nA \"human-readable-writable content format\" should start with a plain part in Markdown (or any other light markup) and after a [delimiter](#delimiter) structured content (for attributes, metadata, tagging etc).\nThe position of structured content should be __below__ the prose, prose is always more important.\n\nFront-matter requires a start_delimiter _and_ an end_delimiter.\nYou can omit the delimiter next to end-of-file (or beginning) and use just __one__ [delimiter](#delimiter).\n\nAnd structured content should be __not__ be mandatory, somtimes you just want to have text.\nIf you have only structured content, just start with the delimiter (like a shebang).\n\nThe structured content should use [YAML](https://yaml.org).\n[Beside yaml](#non-yaml) you could use JSON, xml or csv. Define this in the [delimiter](#delimiter). \n\n## delimiter\n\nTo separate prose from yaml-structure you have to use a separator. This should be a string not already used, but easy to remember. \nJekyll [uses](https://raw.githubusercontent.com/mojombo/mojombo.github.io/master/_posts/2015-06-19-replicated.md) the yaml separator ''---'', but __mandatory__ and before the prose. \n\nLets use the [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) (''#!'') and the used markup.\n\n```\n#!yaml\nmetakeywords: \"some us less words used not by dr who\"\npagetitle: \"Some alternative title\"\n```\n\n### non yaml\n\nIf you want to use an alternative to yaml for [structure](#structure):\n\n```\n#!json\n{\n  \"metakeywords\": \"some us less words used not by dr who\",\n  \"pagetitle\": \"Some alternative title\"\n}\n```\nor even\n\n```\n#!xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003croot\u003e\n  \u003cmetakeywords\u003esome us less words used not by dr who\u003c/metakeywords\u003e\n  \u003cpagetitle\u003eSome alternative title\u003c/pagetitle\u003e\n\u003c/root\u003e\n```\n\nTo have it more easier for users, use some, well known, syntax from prose. Often you need only key-values like [wordpress custom fields](https://codex.wordpress.org/Custom_Fields).\nThe [html definition list](https://www.w3.org/TR/html401/struct/lists.html#h-10.3) is supported by [some](http://talk.commonmark.org/t/description-list/289/12) markdown implementations.\n\n```\n#!md\npagetitle\n: Some alternative title\nmetakeywords\n: some us less words used not by dr who\n```\nThe advantage is, users could use the same syntax for key-values in prose text as for document structure.  \n\n\n\n## Cons\n\nOf course there are some disadvantages:\n\n* not [well formed](https://en.wikipedia.org/wiki/Well-formed_document) like xml, (but it is possible to parse this md-yaml mixup)\n* no datatype specification for structured data (but in most blogs or wikis most metadata are strings and dates)\n\n## In the wild\n\nNot exactly PROSErial, but hitting my main requirement: _optionality_ and _end-of-file_.\n\n* [pandoc extension-yaml_metadata_block](https://pandoc.org/MANUAL.html#extension-yaml_metadata_block)\n\n\n## Status of this document\n\nI thought about this while I was getting user feedack on my ssg [drfly](https://github.com/klml/drfly).\nI am very open for comments or change requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklml%2Fproserial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklml%2Fproserial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklml%2Fproserial/lists"}