1 files changed, 244 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..47d4d26
--- /dev/null
+++ b/README.md
@@ -0,0 +1,244 @@
+# PHP-Blog
+
+PHP-Blog is a simple, database-free blogging web app written in PHP, with the
+support of Markdown and JSON.
+
+## Philosophy
+
+Websites, blogs included, should be able to
+[degrade gracefully over time](https://brandur.org/fragments/graceful-degradation-time).
+For blogs, this means open-sourcing your blog and publishing articles and
+metadata straight to the Git repository.
+
+This project allows you to blog and keep your articles, article metadata, and
+user comments within this repo. This is done through the use of JSON files to
+store article metadata and user comments (instead of using a database), and the
+use of Markdown files to store written articles.
+
+## Installation
+
+Steps:
+
+```bash
+cd yourBlog.com
+```
+
+```bash
+git clone <REPO_URL>
+```
+
+Change the global variables at the top of the `index.php` script:
+
+```php
+$websiteProtocol = 'https://';
+$shortDomain = 'yourBlog.com';
+```
+
+Remove my personal data files:
+
+```bash
+cd _data/ && rm -rf *
+```
+
+Add blank data files:
+
+```bash
+touch comments.json && touch metadata.json
+```
+
+Remove my personal posts:
+
+```bash
+cd ../posts/ && rm -rf *
+```
+
+Add your first post:
+
+```bash
+touch 001-your-first-post.md
+```
+
+For every post you add, also add the applicable JSON object in
+`_data/metadata.json`.
+
+Finally, enable `FallbackResource` in your Apache `.conf` file or in your
+`.htaccess` file:
+
+```apacheconf
+FallbackResource /index.php
+```
+
+## Project Structure
+
+This project uses the structure show below. Continue reading for a brief
+description of each file/folder.
+
+```text
+blog/
+│─── .gitignore
+│─── favicon.ico
+│─── index.php
+│─── LICENSE
+│─── README.md
+│
+└─── _classes/
+│   │─── Comment.php
+│   │─── Parsedown.php
+│   └─── Template.php
+│
+└─── _data/
+│   │─── comments.json
+│   └─── metadata.json
+│
+└─── _functions/
+│   │─── loadJSON.php
+│   │─── loadRSS.php
+│   │─── parseMarkdown.php
+│   └─── submitComment.php
+│
+└─── _templates/
+│   └───template.html
+│
+└─── posts/
+│   │─── 001-your-first-post.md
+│   │─── ...
+│   └─── 999-many-posts-later.md
+│
+└─── static/
+    │─── app.css
+    │─── prism.css
+    └─── prism.js
+```
+
+### File: `index.php`
+
+This file is the FallbackResource for the entire directory, so non-existent
+folders/files requested by users will be sent to `index.php` for processing.
+This file uses a switch statement to read the request URL and direct the user to
+various functions.
+
+Each function in this file will call various other functions/classes and then
+send the output to the template file.
+
+---
+
+### Folder: `_classes`
+
+#### File: `Comment.php`
+
+This class allows for the creation of user comments and provides the
+`saveComment()` function to do so.
+
+#### File: `Parsedown.php`
+
+This class was not created by me, it comes from
+[erusev/parsedown](https://github.com/erusev/parsedown). See his
+[MIT License](https://raw.githubusercontent.com/erusev/parsedown/master/LICENSE.txt)
+for licensing questions on this code.
+
+This class provides numerous capabilities to parse Markdown files and variables
+to HTML.
+
+#### File: `Template.php`
+
+This class allows for the creation of a final HTML page to show the user. The
+`echoTemplate()` function will replace the `{}` templates in the
+`_templates/template.html` file.
+
+---
+
+### Folder: `_data`
+
+#### File: `metadata.json`
+
+Your `metadata.json` file will need to contain an object for each post in the
+`post` folder. If you don't add an object for your new blog post, it won't be
+displayed in the browser. The structure will follow this exactly:
+
+```
+{
+  "id": "001",
+  "title": "Title of Post",
+  "author": "Your Name",
+  "description": "A quick little description for SEO and RSS.",
+  "tag": "my-category",
+  "created": "2018-12-08 00:00:00",
+  "modified": "2018-12-08 00:00:00",
+  "link": "https:\/\/www.example.com\/post\/blog-post-name.html",
+  "published": "Yes"
+}
+```
+
+#### File: `comments.json`
+
+This file is updated server-side as users submit comments on posts. You can
+commit these changes back to your repository by making sure the server-side git
+repo can read & write. Then just create git commits back to your repo from there
+(you can even create periodic cron jobs to do this for you, if you trust it).
+
+You will need to perform the following commands to ensure whatever 'user' is
+writing to the `comments.json` file has the proper permissions. For Apache, the
+user is probably `www-data`.
+
+```bash
+chgrp -R www-data /path/to/website/
+chmod -R g+w _data/comments.json
+```
+
+---
+
+### Folder: `_functions`
+
+#### File: `loadJSON.php`
+
+This file contains four (4) functions that can be called to load JSON data from
+a local file in various ways.
+
+#### File: `loadRSS.php`
+
+This file contains a single function that will grab the `_data/metadata.json`
+file and generate a complete RSS file.
+
+#### File: `parseMarkdown.php`
+
+This file uses the `Parsedown` class to parse a posts or comments from Markdown
+to HTML. It also adds additional attributes to any link found in the Markdown.
+
+#### File: `submitComment.php`
+
+This file uses the `Comment` class to create a comment and then save it to
+`_data/comments.json`.
+
+---
+
+### Folder: `_templates`
+
+#### File: `template.html`
+
+This file is the end result template that will be shown to users, regardless of
+the URL they enter. The main content in the `<body>` and various elements in the
+`<head>` will change depending which function calls this template.
+
+---
+
+### Folder: `posts`
+
+Your `posts` folder will contain the `.md` files that will comprise the body of
+your blog post. Formatting follows standard Markdown guidelines.
+
+---
+
+### Folder: `static`
+
+This folder contains the main CSS file (`app.css`), as well as a pair of
+optional static files from [PrismJS](https://prismjs.com) to enable syntax
+highlighting in any code blocks found in posts or comments.
+
+To remove the optional files, simply delete the unwanted files and remove the
+following from the `pageExtras` parameter string in the `ShowComments()` and
+`ShowPost()` functions in `index.php`:
+
+```html
+<link rel="stylesheet" href="/static/prism.css" />
+<script src="/static/prism.js"></script>
+```