{"id":14979481,"url":"https://github.com/2016rshah/heckle","last_synced_at":"2025-08-20T10:31:52.893Z","repository":{"id":56842991,"uuid":"49100721","full_name":"2016rshah/heckle","owner":"2016rshah","description":":black_nib: Jekyll in Haskell (feat. LaTeX)","archived":false,"fork":false,"pushed_at":"2017-07-19T01:07:37.000Z","size":2770,"stargazers_count":91,"open_issues_count":7,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-03-25T22:03:14.978Z","etag":null,"topics":["blog-engine","haskell","jekyll","latex","static-site-generator"],"latest_commit_sha":null,"homepage":"http://rshah.org/blog/","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/2016rshah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-06T00:13:43.000Z","updated_at":"2023-11-27T05:54:44.000Z","dependencies_parsed_at":"2022-08-29T12:41:20.108Z","dependency_job_id":null,"html_url":"https://github.com/2016rshah/heckle","commit_stats":null,"previous_names":["2016rshah/blatex"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2016rshah%2Fheckle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2016rshah%2Fheckle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2016rshah%2Fheckle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2016rshah%2Fheckle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/2016rshah","download_url":"https://codeload.github.com/2016rshah/heckle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229885865,"owners_count":18139383,"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":["blog-engine","haskell","jekyll","latex","static-site-generator"],"created_at":"2024-09-24T14:00:07.270Z","updated_at":"2024-12-19T10:09:13.064Z","avatar_url":"https://github.com/2016rshah.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Heckle](meta/l3.png)\n\nAn easy to use static-site compiler written in Haskell that supports LaTeX/PDF **and** Markdown/HTML posts. Care has been taken to make it as simple and unopinionated as possible. \n\nIn other words Heckle is basically **Jekyll in Haskell (feat. LaTeX)**.\n\n# Why\n\nWant to use Markdown? Cool. Want to use LaTeX? Cool. Want to use both? Cool. \n\nAlso, Jekyll was [too OP](https://jekyllrb.com/docs/structure/) for my taste. I just wanted to [throw some posts in a directory](https://github.com/2016rshah/heckle#how-to) and be ready to roll. [My own blog](http://www.rshah.org/blog/) uses Heckle with a ported version of [The Hyde Theme](https://github.com/poole/hyde) so it looks like a Jekyll blog, it's more simple to maintain, and it supports LaTeX posts. \n\n# Requirements\n\n## For OSX\n - [Homebrew](https://brew.sh/)\n - [LaTeX](https://latex-project.org/ftp.html) (optional)\n\n## For everybody else\n - [The Haskell Platform](https://www.haskell.org/platform/)\n - [LaTeX](https://latex-project.org/ftp.html) (optional)\n\n# How To\n\nFirst you need to install [Heckle](https://hackage.haskell.org/package/heckle).\n - If you have a mac the easiest way to do so is by running `brew install 2016rshah/tools/heckle`\n - Alternatively if you want to develop heckle I suggest installing by running `stack update \u0026\u0026 stack install heckle`.\n\nAfter you have heckle installed create the directory you want your blog to be based in (`mkdir blog`), initialize a git repository, etc.\n\nWhen you're ready, from inside your new directory run `heckle init`. That will create a skeleton file structure. \n\nNow finally you can do `heckle build` to generate your site. If that succeeds, you will have the example blog up and running!\n\nIt'll look a little like this:\n\n```bash\n.\n├── index.html\n├── index.html.hkl\n├── template.html.hkl\n└── posts\n    ├── example-latex.pdf\n    ├── example-latex.tex\n    ├── example-markdown.html\n    └── example-markdown.md\n```\n\n# Customizing\n\nAt this point, if you open the resulting `index.html` file, everything will look pretty awful. But luckily, you can customize just about everything. \n\n(Also, if you want to get up and running quickly with [the Hyde theme](https://github.com/poole/hyde), follow the instructions in [this README](https://github.com/2016rshah/blog). It will look like [my blog](http://www.rshah.org/blog/) rather than just the skeleton and you can edit things from there.) \n\n### Homepage\n\nThe `index.html.hkl` will basically be the layout you want for the homepage of your blog. Just make sure it is a valid HTML file (with Javascript, CSS, whatever you want) and make sure to keep the following HTML element wherever you want the list of your blog posts to go:\n\n```html\n\u003cul id=\"blog-posts\"\u003e\u003c/ul\u003e\n```\n\nEach blog post will be an `li` element (with the class `blog-post`) containing an `a` tag to the post and a `div` with the date. Heckle will generate something like this:\n\n```html\n\u003cli class=\"blog-post\"\u003e\n    \u003ca class=\"post-link\" href=\"posts/example-post.pdf\"\u003e\n        Example Post\n    \u003c/a\u003e\n    \u003cdiv class=\"post-date\"\u003e\n        1 January 2015\n    \u003c/div\u003e\n\u003c/li\u003e\n```\n\n### LaTeX Posts\n\nHeckle will find all the `.tex` and `.pdf` file pairs in the `posts/` directory and aggregate links to them in your homepage. You will need to compile them yourself (with `pdflatex` probably) just like you normally would and make sure the resulting PDFs look nice. \n\n**You need to ensure that you include a `\\title` and a `\\date` in the preamble of every LaTeX file:**\n\n```tex\n\\date{1 January 2015}\n\\title{Example LaTeX Post}\n```\n\nValid date formats are [outlined below](#valid-date-formats).\n\nWhen you're satisfied, you can run `heckle build` again to update the blog. \n\n### Markdown Posts\n\nThe `template.html.hkl` file is basically the layout file for your Markdown blog posts. Just make sure it is a valid HTML file (with Javascript, CSS, whatever you want) and make sure to keep the following HTML element wherever you want your blog post content:\n\n```html\n\u003cdiv id=\"blog-post\"\u003e\u003c/div\u003e\n```\n\n**You need to ensure that you include specific commented meta-data including the title, author, and date in every Markdown file**. The first three lines of each markdown file need to be formatted as follows:\n\n```markdown\n% \u003cTITLE\u003e\n% \u003cAUTHOR\u003e\n% \u003cFORMATTED-DATE\u003e\n``` \n\nValid date formats are [outlined below](#valid-date-formats).\n\nHeckle will find all the `.md` files and convert them to `.html` with the help of [Pandoc](http://pandoc.org/). Then it will insert the resulting HTML into your `template.html.hkl` file at the specified location. Finally, it aggregates links to all the posts in your homepage. \n\nWhen you're satisfied, you can run `heckle build` again to update the blog. \n\n## Valid Date Formats\n\nThese are the valid date formats: \n - `1 January 2016`\n - `January 1, 2016`\n - `9:47AM 1 January 2016`\n - `9:47AM January 1, 2016`\n\nFeel free to mix and match between the formats. If you would like to support a different date format, let me know by opening [an issue](https://github.com/2016rshah/heckle/issues).  \n\n# BlaTeX ?\nThis project used to be called BlaTeX and was specifically for LaTeX/PDF posts (it did not support Markdown/HTML). It was created over the course of my senior year in high-school as my [senior research project](https://github.com/2016rshah/Meta-BlaTeX). Eventually I decided to [support Markdown as well](https://github.com/2016rshah/heckle/issues/5) and thus Heckle was born.\n\n# See also:\n  - The Hackage package: https://hackage.haskell.org/package/heckle\n  - PDFs are the future ?¿?: http://www.rshah.org/blog/posts/what-is-the-web.pdf\n  - The Abstraction Progression of BlaTeX: http://www.rshah.org/blog/posts/abstraction-progression-blatex.pdf\n  - The culmination of BlaTeX in my final paper: https://github.com/2016rshah/Meta-BlaTeX/blob/master/Paper/final.pdf\n  - My powerpoint presentations about Haskell/BlaTeX: https://github.com/2016rshah/Meta-BlaTeX/tree/master/Presentations\n  - My poster for BlaTeX: https://github.com/2016rshah/Meta-BlaTeX/blob/master/Poster/Poster.pdf\n  - The historical repo for BlaTeX: https://github.com/2016rshah/Meta-BlaTeX/tree/master/BlaTeX\n  - How BlaTeX became Heckle: http://www.rshah.org/blog/posts/birth-of-heckle.html","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2016rshah%2Fheckle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F2016rshah%2Fheckle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2016rshah%2Fheckle/lists"}