{"id":19851744,"url":"https://github.com/ajkavanagh/vimwiki-publishing-system","last_synced_at":"2025-05-02T00:30:56.294Z","repository":{"id":54510045,"uuid":"213472847","full_name":"ajkavanagh/vimwiki-publishing-system","owner":"ajkavanagh","description":"Programs/scripts to help with publishing websites using vimwiki as an authoring environment.","archived":false,"fork":false,"pushed_at":"2023-07-31T19:42:54.000Z","size":792,"stargazers_count":9,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T19:22:34.694Z","etag":null,"topics":["ginger","pandoc","vimwiki"],"latest_commit_sha":null,"homepage":"","language":"Haskell","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/ajkavanagh.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","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-10-07T19:49:18.000Z","updated_at":"2024-12-08T05:25:49.000Z","dependencies_parsed_at":"2022-08-13T18:10:43.888Z","dependency_job_id":null,"html_url":"https://github.com/ajkavanagh/vimwiki-publishing-system","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajkavanagh%2Fvimwiki-publishing-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajkavanagh%2Fvimwiki-publishing-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajkavanagh%2Fvimwiki-publishing-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajkavanagh%2Fvimwiki-publishing-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajkavanagh","download_url":"https://codeload.github.com/ajkavanagh/vimwiki-publishing-system/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251966431,"owners_count":21672666,"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":["ginger","pandoc","vimwiki"],"created_at":"2024-11-12T13:30:50.492Z","updated_at":"2025-05-02T00:30:51.286Z","avatar_url":"https://github.com/ajkavanagh.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vimwiki-publishing-system\n\n(Note the name is probably going to change).\n\nThe premise: allow writing in vimwiki, and publish as a static website.\n\nSo it's a site producer that uses files according to a `site.yaml` or similarly\nnamed file.  This is much more interesting as it forms the basis for generating\narbitrary sites from pages that can be authored (and linked) in vimwiki.  It\nalso means that *other* editors could be used, which might make it useful for\nother people.\n\nThus there is one executable generated by this application:\n\n* `sitegen` -- use a `site.yaml` to generate a set of HTML files from the files\n  within the same wiki doc.  Use the `-h` option to see the various options.\n\n# Current State\n\nSo it started out as an itch to scratch.  I wanted to edit my website 'pages'\nin (n)vim but also have a sense of being able to organise the pages using\na wiki style.  But the output didn't need to reflect that.\n\nSo I could have used Hakyl, but I also wanted to build something using\nPolysemy.  And, as I am also a Python programmer, I wanted to try out Ginger\ntemplates, which are a (really good) emulation of the Jinga2 in Haskell.  This\nmeant that a single binary, a yaml file and a bunch of markdown files is all\nthat is needed to generate a site.\n\nIt's also likely that once it's \"good enough\" for my usage that I'll probably\nstop working on it, except when I need a new feature.  However, once it's more\nfinished, I'd be happy to accept pull requests!\n\n## What works\n\n* Generating source files and index pages (with custom selections of pages)\n* Tags and Categories (as two different taxonomies).  It'd probably be useful\n  to just make these general, but we're not there yet.\n* 404 custom page\n* Atom /feed.atom (but not configurable)\n* Theme file and overrides.\n* Site overrides of theme files.\n* Placing output wherever you want in the hierachy.\n* Cleaning up output when files change (e.g. if the file shouldn't exist after\n  the site is rendered, then it can be deleted.)\n* Ginger (Jinja2 compatible) templates for pages.\n* Table-of-Contents generation (although it's not heavily tested)\n* Rich and plain content possible.\n* Syntax highlighting using Skylight and Pandoc.\n* Pandoc Markdown with most of the options turned on.\n* Draft pages (by default)\n* Resolving links (and removing ones that point to drafts or inaccessible\n  pages).\n\n## What is still on my todo list\n\n  - [ ] Document how to make it all work.\n  - [ ] Do less work; detect when things haven't changed.\n  - [ ] Generate a sitemap.xml file for the site as needed.\n  - [ ] Have a 'server' mode for use when writing files.  i.e. something that\n        will serve files and regenerate on demand for a browser.\n\n# The Site generator\n\n## How do you work with it?\n\nThe user creates and edits pages as normal in Vimwiki pages and links.  i.e. It\nlooks like a normal wiki of interconnected pages.  Vimwiki can navigate around\nthose pages assuming it is configured appropriately.  Vimwiki can also 'publish'\nthose pages using `VimwikiAll2HTML` which would convert every page.  In this\ncase, the `vm2html` would just remove the `sitegen` specific page config and\ngenerate individual wiki pages.\n\nNote: [vw2html](https://github.com/ajkavanagh/vw2html) is another program that\ncan convert pages.  It will eventually get the option to drop the page header\n(which it doesn't at present).\n\nHowever, if there are no `sitegen` config sections on any pages, then no site\nwill be generated (apart from, perhaps, the index page, but with no content).\n\nBut first there must be a `site.yaml`.  Then pages that should be published in\nthe site must have a `sitegen` config section at the top of the page to indicate\nthat it should be included in the site.\n\n### The `site.yaml` config file\n\nThe configuration/control for the site build will be in a yaml file.  This will\nspecify the source and destination directories, how different parts are mapped\nand what features are enabled in the site build.  Also, the location of template\nfiles, and how they are controlled.\n\n\ne.g.\n```yaml\n# key/values available in the site's YAML document\n# the values provided are the default values\n---\nsite: \u003csite-identifier\u003e\nsource: ./src  # the directory (relative, if wanted, to the site.yaml) to start\n               # looking for sitegen pages.\noutput-dir: ./html\nextension: .md # the extension of files that may be sitegen page parts\nindex-page-name: index # string representing the custom page name for the index\ntemplates-dir: ./templates # directory to find templates\ntemplate-ext: .html.j2  # the extension used for templates\nstatic-dir: ./static    # where the statics that get copied to the site live;\n                        # e.g. CSS and JS files.\nindex-files: True       # generate thing/index.html rather than thing.html\ngenerate-tags: true  # should sitegen generate a tags page\ngenerate-categories: true  # should sitegen generate categories\n```\n\nSee `./src/Lib/SiteGenConfig.hs` for more details.\n\n\n### The `sitegen` header in the page\n\nFor a page to be recognised by `sitegen` it needs to have a header than\nidentifies the page (or page fragment) as a page to be processed.\n\n`sitegen` recognises three hyphens `--- \u003ckeyword\u003e` as a `sitegen` instruction.\nThis will be stripped out of the page and processed.  The `sitegen` config in\na page can include:\n\nNote: I'm not sure I want to keep the 'sitegen' bit of the yaml file.  It was\nto nail it down, but I think it just being a yaml header is probably good\nenough.\n\n```yaml\n--- sitegen\ntitle: The page \u003ctitle\u003e value\ntemplate: default  # the template file (minus .extension) to render this page with\nstyle: style.css   # the style sheet to apply to this page.\ntags: [tag1, tag2] # tags to apply to the page\ncategory: cat1     # The SINGLE category to apply to the page.\ndate: 2019-10-11   # The Date/time to apply to the page\nupdated: 2019-10-12 # Date/time the page was updated.\nroute: code/slug-name  # The permanent slug to use for this page.\nauthors: [tinwood]  # Authors of this page.\npublish: false        # The default is false; set to true to actually publish it.\nsite: \u003csite-identifier\u003e # the site that this belongs to. 'default' is the\n                        # default site identifier.\n\u003cmaybe more\u003e\n---                # this indicates the end of the header.\n# Content goes here ...\n```\n\nSee `./src/Types/Header.hs` for more details on the parts of the page header.\n\nThe `route` is interesting as it can determine what section the page fits into.\nThis (could) auto-select the template type for the page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajkavanagh%2Fvimwiki-publishing-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajkavanagh%2Fvimwiki-publishing-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajkavanagh%2Fvimwiki-publishing-system/lists"}