forked from 20xd6/simple_blog
Merge pull request 'Add documentation.' (#13) from manfromhuh/simple_blog:master into master
Reviewed-on: 20xd6/simple_blog#13
This commit is contained in:
commit
87a07aaf02
135
README.md
135
README.md
@ -1 +1,136 @@
|
||||
# simple_blog
|
||||
|
||||
simple_blog is a basic blogging platform. It is designed to be a straightforward way to publish articles written in Markdown and display them using a renderer written in PHP. There is no login page or any way to manage simple_blog from the web. All management is done via the command line. This can be done with a shell script or with the python based [simple_blog_cms](/git/20xd6/simple_blog_cms).
|
||||
|
||||
## Requirements
|
||||
|
||||
* Currently tested with PHP 7.4
|
||||
* Some shell access is necessary.
|
||||
* The recommend way is via ssh.
|
||||
* I don't see a technical reason it can't work with a web manager like cPannel or Ajenti as long has you have the ability to upload files and manage files.
|
||||
|
||||
## Publishing
|
||||
|
||||
Publishing can be done manually or with a script that accomplishes the following tasks.
|
||||
|
||||
1. Create a directory under `/blog/by_year/$CURRENT_YEAR/$CURRENT_MONTH/`
|
||||
* For a post in January of 2022 this would be `/blog/by_year/2022/01/`
|
||||
* The directory should start with a numeral otherwise it will be sorted alphabetically
|
||||
2. Place a file named `article.md` containing the MarkDown formatted text of the article in the directory created in the previous step
|
||||
3. Copy or symlink `/common/index.php` into the directory created in step 1
|
||||
4. Place a file named `tags` containing a comma separated list of tags for the article in the directory created in step 1
|
||||
5. Add the article's relative path and title to `/by_tag/tags.csv` under the appropriate headings.
|
||||
|
||||
The recommended method is to use [simple_blog_cms](/git/20xd6/simple_blog_cms "simple_blog_cms")
|
||||
|
||||
## Article Tags
|
||||
|
||||
### Per-article List
|
||||
|
||||
A file named `tags` is placed in the directory for each article. It should contain a comma separated list of tags being applied to the article. This will be parsed and displayed by [`/common/md_read.php`](/git/20xd6/simple_blog/src/branch/master/common/md_read.php) at the bottom of the article.
|
||||
|
||||
### by_tags
|
||||
|
||||
This folder contains an index file that displays an article list generated by parsing the `tags.csv` file. A format example is displayed below.
|
||||
|
||||
| "PHP" | "JS" | "Religion" | "Catholic" |
|
||||
| ----- | ---- | ---------- | ---------- |
|
||||
| "/blog/by_year/2021/10/03_Forcing_Elements_to_reload/" | "/blog/by_year/2021/10/03_Forcing_Elements_to_reload/" |"/blog/by_year/2021/10/reproduction_of_Gainer_Bishop_Ronald_4-1-16/" | reproduction_of_Gainer_Bishop_Ronald_4-1-16/" |
|
||||
| "Forcing page elements to reload" | "Forcing page elements to reload" | "Open Letter to Bishop Ronald Gainer" | "Open Letter to Bishop Ronald Gainer" |
|
||||
| "/blog/by_year/2022/06/28_A_Test_Post/"| | |
|
||||
| "A Test Post" | | |
|
||||
|
||||
|
||||
## File Descriptions
|
||||
|
||||
### blog
|
||||
|
||||
Contains the blog articles. The articles are placed in subdirectories of `by_year` according to the year and month they were published.
|
||||
|
||||
```
|
||||
├── by_year
|
||||
│ ├── 2021
|
||||
│ │ ├── 12
|
||||
│ │ └── index.php -> /path/to/common/index.php
|
||||
│ ├── 2022
|
||||
│ │ ├── 01
|
||||
│ │ ├── 02
|
||||
│ │ └── index.php -> /path/to/common/index.php
|
||||
│ └── index.php
|
||||
└── index.php -> /path/to/common/index.php
|
||||
```
|
||||
|
||||
### common
|
||||
|
||||
This directory contains the files and libraries used to render the site's pages.
|
||||
|
||||
#### Composer files
|
||||
* composer.json
|
||||
* composer.lock
|
||||
* [/common/vendor]() - Stores the composer files and libraries managed via composer.
|
||||
|
||||
#### CSS
|
||||
|
||||
* [styles.css](/git/20xd6/simple_blog/src/branch/master/common/styles.css) - The main site CSS.
|
||||
* [jmenu.css]() - Used to render the responsive menus.
|
||||
* [print.css]() - Used to style printed pages.
|
||||
* [gallery.css]() - Styles the floating
|
||||
|
||||
#### JS
|
||||
|
||||
* font_size.js
|
||||
* [page_format.js]() - The main JS file used for formatting and adding extra functions to pages.
|
||||
* gallery.js
|
||||
|
||||
#### PHP
|
||||
|
||||
* [footer.php]() - The common page footer. Contains copyright information and links to the license.
|
||||
* [get_month_name.php]() - Translates a numeral month into the corresponding name. I.E. 01 into January.
|
||||
* [h1_month.php]() - Adds the proper `<h1>` heading based on the location of the
|
||||
* [header.php]() - The common page header.
|
||||
* [index.php]() - The index file used for most of the pages on the site.
|
||||
* [markdown.php]()
|
||||
* [md_read.php]() - Renders Markdown files and adds
|
||||
* [menu.php]() - Generates the blog menu items in the navigation menu.
|
||||
* [modal.php]() - Adds the modal `<div>` for displaying the image pop out.
|
||||
* [page_menu.php]() - Generates a menu from the files and directories where it's run from.
|
||||
* [page_menu_table.php]()
|
||||
* [path_menu.php]()
|
||||
|
||||
#### /common/error_pages/
|
||||
|
||||
* [/common/403.php]() - The 403 not allowed page.
|
||||
* [/common/404.php]() - The 404 page.
|
||||
* [/common/500.php]() - Displayed for all HTTP 500 errors
|
||||
|
||||
#### /common/imgs/
|
||||
|
||||
Images used site wide.
|
||||
|
||||
* [cursor.gif]() - Blinking cursor used on the front page.
|
||||
* [icon-rss.png]() - RSS icon
|
||||
|
||||
|
||||
#### /common/prisim
|
||||
|
||||
Files for the prism syntax highlighter.
|
||||
|
||||
### license
|
||||
|
||||
This directory contains all the licensing information for simple_blog. simple_blog is licensed under the GPLv2 but uses components that are licensed under the MIT Open Source license. These components are:
|
||||
|
||||
* [Jmenu](https://github.com/jamesjohnson280/JMenu)
|
||||
* [Parsedown](https://github.com/erusev/parsedown)
|
||||
* [Parsedown-extra](https://github.com/erusev/parsedown-extra)
|
||||
|
||||
#### index.php
|
||||
|
||||
Displays all of the reverent license and the components they apply to.
|
||||
|
||||
* simple_blog is licensed GPLv2. This cannot be changed.
|
||||
* Default license for articles published. This is [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/) by default. This licensed can be changed however the site admin wishes.
|
||||
* [Jmenu](https://github.com/jamesjohnson280/JMenu) is licensed MIT. This cannot be changed.
|
||||
* [Parsedown](https://github.com/erusev/parsedown) is licensed MIT. This cannot be changed.
|
||||
* [Parsedown-extra](https://github.com/erusev/parsedown-extra) is licensed MIT. This cannot be changed.
|
||||
|
||||
Copies of all these licenses can be found in the `/license/` directory.
|
||||
@ -1,4 +1,5 @@
|
||||
<?php
|
||||
//Parses it's passed input to convert it to a month name.
|
||||
function get_month_name($passed_var){
|
||||
switch($passed_var){
|
||||
case "01":
|
||||
|
||||
@ -1,4 +1,5 @@
|
||||
<?php
|
||||
//Sets the proper level 1 heading for the folder.
|
||||
include_once ($_SERVER['DOCUMENT_ROOT'].'/common/get_month_name.php');
|
||||
$current_dir = basename(getcwd());
|
||||
$named_month = get_month_name($current_dir);
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en-US">
|
||||
<?php
|
||||
function Title() {
|
||||
//Sets the page title based on the name of the current directory
|
||||
function Title() {//Needs cleanup.
|
||||
//~ $new_title = $_SERVER['REQUEST_URI'];
|
||||
|
||||
//~ $new_title = preg_replace("/^^\//i", "", $new_title);
|
||||
@ -27,7 +28,7 @@
|
||||
?>
|
||||
<head>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
|
||||
<?php
|
||||
<?php//If a tags file is present parse it and add any tags found to the renderd page's metadata.
|
||||
if(file_exists('tags')){
|
||||
$tag_data_raw = fopen('tags',"r");
|
||||
$tag_data = fread($tag_data_raw, filesize('tags'));
|
||||
|
||||
@ -1,7 +1,10 @@
|
||||
<?php
|
||||
//The common file used to render pages on the blog.
|
||||
include_once ($_SERVER['DOCUMENT_ROOT'].'/common/header.php');
|
||||
include_once ($_SERVER['DOCUMENT_ROOT'].'/common/menu.php');
|
||||
if (file_exists('article.md')){
|
||||
//Looks for an article.md to see if the current directory is an article or not
|
||||
//If it is not then it is a menu page.
|
||||
if (file_exists('article.md')){
|
||||
include_once ($_SERVER['DOCUMENT_ROOT'].'/common/md_read.php');
|
||||
} else {
|
||||
include_once ($_SERVER['DOCUMENT_ROOT'].'/common/h1_month.php');
|
||||
|
||||
@ -1,8 +1,10 @@
|
||||
//
|
||||
function format_page(){//Set the title of the page based on the main header, <h1>, tag.le != '' )){
|
||||
if ( document.getElementsByTagName('h1').length !== 0){
|
||||
document.title = document.getElementsByTagName('h1')[0].innerText;
|
||||
}
|
||||
//detect if the page contains code blocks to be highlighted and loads the prisim.js and prism.css files to accomplish this.
|
||||
//Detect if the page contains code blocks to be highlighted and loads the
|
||||
//prisim.js and prism.css files if codeblocks are found.
|
||||
code_tag = document.getElementsByTagName('code').length;
|
||||
if ( code_tag !== 0 ){
|
||||
var script = document.createElement('script');
|
||||
@ -15,11 +17,14 @@ function format_page(){//Set the title of the page based on the main header, <h1
|
||||
document.head.appendChild(script);
|
||||
document.head.appendChild(style_sheet);
|
||||
}
|
||||
if ( document.getElementById("font_btns") ){//Show the font selection buttons.
|
||||
//Sets the displayed fontsize.
|
||||
//This functionality won't work without JavaScript enabled. For this reason the
|
||||
//buttons won't be shown if this script isn't run.
|
||||
if ( document.getElementById("font_btns") ){//Show the font selection buttons.
|
||||
document.getElementById("font_btns").style.display = 'inline';
|
||||
var font_size = read_cookie("font_size");
|
||||
var font_size = read_cookie("font_size");//reads a saved value for fontsize from the site cookie
|
||||
if ( font_size != "" || font_size != "medium" ){
|
||||
font_set(font_size);
|
||||
font_set(font_size);//insure a sane default
|
||||
}
|
||||
}
|
||||
if ( document.getElementById("search_inputs") ){//Show the search box and button on the tags page.
|
||||
@ -43,7 +48,7 @@ function format_page(){//Set the title of the page based on the main header, <h1
|
||||
});
|
||||
}
|
||||
}
|
||||
function font_set(size_to_set){
|
||||
function font_set(size_to_set){//Set a cookie to remember the fontsize selection.
|
||||
document.getElementById("article").style.fontSize = size_to_set;
|
||||
set_cookie("font_size",size_to_set);
|
||||
}
|
||||
@ -52,7 +57,7 @@ function focus_element(element_id){
|
||||
ele_to_focus.focus();
|
||||
ele_to_focus.select();
|
||||
}
|
||||
function tag_search(){
|
||||
function tag_search(){//searches in the avaliable tags and displays all articles matching the searched tag.
|
||||
var search_input, filter, tag_list, li, a, i;
|
||||
search_input = document.getElementById("tag_sort");
|
||||
filter = search_input.value.toUpperCase();
|
||||
@ -66,9 +71,8 @@ function tag_search(){
|
||||
li[i].style.display = "none";
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
function title_search(){
|
||||
function title_search(){//searches for matches in the article titles rather than tags. Allows more granular search
|
||||
var search_input, filter, tag_list, li_list, ol, a, i;
|
||||
search_input = document.getElementById("title_sort");
|
||||
filter = search_input.value.toUpperCase();
|
||||
@ -88,7 +92,7 @@ function title_search(){
|
||||
}
|
||||
|
||||
}
|
||||
function search_toggle(){
|
||||
function search_toggle(){//Toggles if the unit being sorted on is the article title or tag
|
||||
if (document.getElementById("tag_sort")){
|
||||
document.getElementById("tag_sort").placeholder = "Search Titles";
|
||||
document.getElementById("tag_sort").onkeyup = function() {title_search()};
|
||||
@ -107,10 +111,10 @@ function search_toggle(){
|
||||
focus_element("tag_sort");
|
||||
}
|
||||
}
|
||||
function set_cookie(prop_name, prop_value){
|
||||
function set_cookie(prop_name, prop_value){//sets a passed cookie property and value.
|
||||
document.cookie = prop_name + "=" + prop_value + ";path=/;SameSite=Strict;";
|
||||
}
|
||||
function read_cookie(cname){
|
||||
function read_cookie(cname){//reads a property value
|
||||
let prop_name = cname + '=';
|
||||
let decoded_cookie = decodeURIComponent(document.cookie);
|
||||
let split_cookie = decoded_cookie.split(';');
|
||||
@ -125,11 +129,11 @@ function read_cookie(cname){
|
||||
}
|
||||
return "";
|
||||
}
|
||||
function printDiv(divName) {
|
||||
function printDiv(divName) {//Formats the page for printing.
|
||||
var printContents = document.getElementById(divName).innerHTML;
|
||||
w=window.open();
|
||||
w.document.write(printContents);
|
||||
w.print();
|
||||
w.close();
|
||||
}
|
||||
window.onload = format_page;
|
||||
window.onload = format_page;//loades the page formatting script.
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
<?php
|
||||
include_once ($_SERVER['DOCUMENT_ROOT'].'/common/get_month_name.php');
|
||||
|
||||
//Removes the number used to keep articles in post order from the displayed title.
|
||||
function remove_sorting_number($link_title){
|
||||
$first_three = mb_substr($link_title, 0, 3,"UTF-8");
|
||||
|
||||
@ -31,14 +32,14 @@ if (file_exists($dir) && is_dir($dir) ) {
|
||||
$file_array[] = $file;
|
||||
}
|
||||
}
|
||||
foreach($file_array as $file) {
|
||||
$_replace = array('.php', '.html', '.htm');
|
||||
$link_title = str_replace('_',' ',$file);
|
||||
foreach($file_array as $file) {//Renders the folder names as more readable titles.
|
||||
$_replace = array('.php', '.html', '.htm');//Remove file extensions from webpages.
|
||||
$link_title = str_replace('_',' ',$file);//Remove undersores and replace them with spaces
|
||||
$link_title = str_replace($_replace,'',$link_title);
|
||||
$link_title = ucwords($link_title);
|
||||
$link_title = get_month_name($link_title);
|
||||
$link_title = remove_sorting_number($link_title);
|
||||
echo("<ul><li><a href='$file'> $link_title </a></li></ul>\n");
|
||||
$link_title = ucwords($link_title);//Set the first letter of each word to upercase.
|
||||
$link_title = get_month_name($link_title);//
|
||||
$link_title = remove_sorting_number($link_title);//Removes the number used to keep articles in post order from the displayed title.
|
||||
echo("<ul><li><a href='$file'> $link_title </a></li></ul>\n");//Output the result.
|
||||
}
|
||||
}
|
||||
else {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user