diff options
| author | Christian Cleberg <[email protected]> | 2026-08-02 15:29:36 -0500 |
|---|---|---|
| committer | Christian Cleberg <[email protected]> | 2026-08-02 15:29:36 -0500 |
| commit | 12df45442b37cb920bba96fa48edc9fda8b77f89 (patch) | |
| tree | ebcf18fc38db6c1bcb66955288f5ce22ff63e4a3 /README.md | |
| parent | a0b426147d99ecb146dc655378b7c563ea4f4769 (diff) | |
| download | php-blog-12df45442b37cb920bba96fa48edc9fda8b77f89.tar.gz php-blog-12df45442b37cb920bba96fa48edc9fda8b77f89.tar.bz2 php-blog-12df45442b37cb920bba96fa48edc9fda8b77f89.zip | |
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 244 |
1 files changed, 0 insertions, 244 deletions
diff --git a/README.md b/README.md deleted file mode 100644 index 47d4d26..0000000 --- a/README.md +++ /dev/null @@ -1,244 +0,0 @@ -# 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> -``` |
