{"id":15524052,"url":"https://github.com/elazar/scribing","last_synced_at":"2025-03-05T09:34:49.842Z","repository":{"id":56976271,"uuid":"91198687","full_name":"elazar/scribing","owner":"elazar","description":"A simple static blog generator","archived":true,"fork":false,"pushed_at":"2018-06-22T02:37:36.000Z","size":16,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-24T13:03:07.631Z","etag":null,"topics":["blog","commonmark","php","static-site-generator"],"latest_commit_sha":null,"homepage":null,"language":"PHP","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/elazar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-13T19:40:10.000Z","updated_at":"2025-02-04T00:18:25.000Z","dependencies_parsed_at":"2022-08-21T11:20:31.160Z","dependency_job_id":null,"html_url":"https://github.com/elazar/scribing","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elazar%2Fscribing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elazar%2Fscribing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elazar%2Fscribing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elazar%2Fscribing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elazar","download_url":"https://codeload.github.com/elazar/scribing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242001560,"owners_count":20055871,"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","commonmark","php","static-site-generator"],"created_at":"2024-10-02T10:48:58.194Z","updated_at":"2025-03-05T09:34:49.518Z","avatar_url":"https://github.com/elazar.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Scribing\n\nScribing is a simple static blog generator, or [static site\ngenerator](https://davidwalsh.name/introduction-static-site-generators)\ndesigned for generating a blog, written in PHP.\n\n## Installation\n\nUse [Composer](https://getcomposer.org/).\n\n```sh\ncomposer require elazar/scribing\n```\n\n## Example\n\nIf you'd like to see a working example of a site that uses Scribing, check out [this repository](https://github.com/elazar/blog-content).\n\n## Content\n\nContent for Scribing is written in [Common Markdown](http://commonmark.org).\n\nScribing supports two document types: posts and pages.\n\n### Posts\n\nPosts include a top level heading containing a title followed by a date\nformatted with emphasis.\n\n```markdown\n# Post Title\n\n*September 28, 2017*\n\nContent goes here\n```\n\nScribing both builds an individual file for each post and also includes a link\nto it on an archive page. Its path is derived from the date and title included\nin the Markdown content file.\n\n### Pages\n\nPages include a top level heading, but unlike posts, they are not\ndate-specific. Often, their content rarely changes.\n\n```markdown\n# Page Title\n\nContent goes here\n```\n\nScribing builds a file for each page at a path based on the name of the\nMarkdown content file.\n\n## Design\n\nScribing uses the [Plates](http://platesphp.com) template engine.\n\nWhen it is run, Scribing requires a template path to be specified. This path\nmust reference a directory containing two Plates template files: the layout\ntemplate and the archive page template.\n\n### Layout Template\n\n`layout.php` is used as the layout template for both posts and pages.\n\nHTML generated from Markdown content is passed into the `$content` variable.\n\nThe top level heading is passed into the `$title` variable. It can be used in\nthe document's `\u003ctitle\u003e` tag.\n\n### Archive Template\n\n`archive.php` is used to generate the content for the archive page. Unlike the\ncontent for other pages, archive page content is generated from data contained\nin post content files rather than being created manually in Markdown.\n\nAn associative array of posts keyed by year is passed into `$posts`, where the\nvalue referenced by each year is an enumerated array of posts for that year.\nEach post is represented by an associative array containing `'date'`, `'url'`,\nand `'title'` keys.\n\n### Common Data\n\nFor any common data that needs to be shared between templates, such as for\nnavigation, create a PHP file that returns an array of data.\n\n```php\nreturn [\n    'nav' =\u003e [\n        '/' =\u003e 'Home',\n        '/archive' =\u003e 'Archive',\n        // ...\n    ],\n];\n```\n\n## Generating the Site\n\nTo generate the static files for a blog based on the post and page content\nfiles and Plates template files you've created, you use the `scribing` console\ncommand.\n\n### Posts and Pages\n\n`scribing` supports multiple subcommands, two of which are: `build:posts` and\n`build:pages`. Both use the same parameters.\n\n```\nbuild:posts [--templateData=path/to/data.php] \u003csourcePath\u003e \u003cdestinationPath\u003e \u003ctemplatePath\u003e\n```\n\n`--templateData` is optional and used to specify a path to a common data file,\nif one is needed.\n\n`\u003csourcePath\u003e` is a directory that contains the source files for posts or pages.\n\n`\u003cdestinationPath\u003e` is a directory into which `scribing` will store the files\nit generates.\n\n`\u003ctemplatePath\u003e` is a directory containing the template files.\n\nTo build pages instead of posts, simply substitute `build:pages` for\n`build:posts` in the example above.\n\n### Feed\n\nTo build a feed from posts, `scribing` supports a `build:feed` subcommand.\n\n```\nbuild:feed --feedTitle=\"Feed Title\" --feedLink=\"https://example.com/feed.xml\" \u003csourcePath\u003e \u003cdestinationPath\u003e\n```\n\n`--feedTitle` is a title for the feed required by the Atom format\n\n`--feedLink` is an absolute URL to the feed required by the Atom format\n\n`\u003csourcePath\u003e` is a directory that contains the source files for posts to include in the feed\n\n`\u003cdestinationPath\u003e` is a directory into which `scribing` will store the feed file\n\n## Using GitHub Pages\n\nIf you are using Scribing to generate a site to be hosted on [GitHub\nPages](https://help.github.com), set up a repository to store your content,\ntemplates, stylesheets, images, etc. that is separate from the repository that\nGitHub uses to display the site.\n\nHere's a recommended directory structure:\n\n```\n.\n├── content\n│   ├── pages\n│   └── posts\n├── images\n├── scripts\n├── styles\n└── templates\n```\n\nThe purpose of most of the directories above should be self-explanatory.\n\nThe `scripts` directory is intended to house build and utility scripts used to\ntweak or deploy the files generated by Scribing.\n\nFor example, Scribing doesn't handle stylesheet or content license files, so\nthese have to be manually copied to the build directory.\n\nIf you want to [create a custom 404\npage](https://help.github.com/articles/creating-a-custom-404-page-for-your-github-pages-site/),\nyou can author the content as a normal page and then move the generated file to\nan appropriate location in your build script like so:\n\n```sh\nmv build/404/index.html build/404.html ; rm -fR build/404\n```\n\nIf you'd like to locate the latest post and use that as the landing page for\nthe site, you can do it like so:\n\n```sh\nLATEST=`find build/ -type f | grep -E '[0-9]+' | grep -v '404' | sort -nr | head -n 1`\ncp \"$LATEST\" build/index.html\n```\n\nHere are some related resources for further reading:\n\n* [Securing your GitHub Pages site with HTTPS](https://help.github.com/articles/securing-your-github-pages-site-with-https/)\n* [Quick start: Setting up a custom domain](https://help.github.com/articles/quick-start-setting-up-a-custom-domain/)\n* [GitHub Pages and Single-Page Apps](https://dev.to/_evansalter/github-pages-and-single-page-apps)\n* [GitHub Pages Deployment - Travis CI](https://docs.travis-ci.com/user/deployment/pages/)\n\n## License\n\nThe source code for Scribing is licensed under the [MIT License](https://en.wikipedia.org/wiki/MIT_License).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felazar%2Fscribing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felazar%2Fscribing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felazar%2Fscribing/lists"}