From 79688e6aa2473b40236afb50bd36c8d53ccbc881 Mon Sep 17 00:00:00 2001 From: AtaS Date: Mon, 8 Jan 2024 07:02:37 +0000 Subject: [PATCH] Update README.md --- README.md | 96 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 52 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 0d2c808..9ee4889 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,30 @@ # Ata's SSG - PHP-based Vanilla-HTML Static Site Generator for GitHub Pages -* No frameworks. -* No templating. -* No plugins. -* Just very basic PHP and HTML. +- No frameworks. +- No templating. +- No plugins. +- Just very basic PHP and HTML. Simply clone, configure, and deploy! ## Demo - Examples -* This repo's CI deploys to: https://ssg-test.atasasmaz.com -* Production example: https://www.atasasmaz.com + +- This repo's CI deploys to: https://ssg-test.atasasmaz.com +- Production example: https://www.atasasmaz.com ## Quick Start 1. Clone the repo 2. `cd` into project dir, run `$ composer update` 3. Run `$ make dev-server` (needs docker) - Your local php site will be running at **http://localhost:8001** -4. Add your markdown pages and posts to `./pages` and `./posts`, or .php files anywhere and commit & push to a new - repo. - * _Ensure `.github` dir from here is included in your new repo._ -* Your site will be alive on GitHub Pages! + Your local php site will be running at **http://localhost:8002** +4. Add your markdown pages and posts to `./pages` and `./posts`, or .php files anywhere and commit & push to a new + repo. + - _Ensure `.github` dir from here is included in your new repo._ + +- Your site will be alive on GitHub Pages! -🔴 **IMPORTANT: Your repo name** should be `github-username.github.io` if you want to use GitHub Pages subdomain. To +🔴 **IMPORTANT: Your repo name** should be `github-username.github.io` if you want to use GitHub Pages subdomain. To use a **Custom Domain**, check my docs for [GITHUB PAGES](GITHUB-PAGES.md). ## Configuring GitHub Pages @@ -30,49 +32,51 @@ use a **Custom Domain**, check my docs for [GITHUB PAGES](GITHUB-PAGES.md). See [GITHUB PAGES](GITHUB-PAGES.md). ## Related projects -* Custom GitHub Action: https://github.com/atas/ssg-html-builder-action -* Docker image: https://github.com/atas/ssg-builder-image -* PHP Lib: https://github.com/atas/ssg-system-php + +- Custom GitHub Action: https://github.com/atas/ssg-html-builder-action +- Docker image: https://github.com/atas/ssg-builder-image +- PHP Lib: https://github.com/atas/ssg-system-php ## Why Ata's SSG? -* **Basic PHP**: PHP stands as a robust templating and server-side language, eliminating the need to learn new +- **Basic PHP**: PHP stands as a robust templating and server-side language, eliminating the need to learn new templating languages. -* **No Framework**: No learning a new frameworks or application. Familiarity with basic PHP is enough to get started. Just create your own HTML and PHP files. +- **No Framework**: No learning a new frameworks or application. Familiarity with basic PHP is enough to get started. Just create your own HTML and PHP files. -* **Markdown & Beyond**: Write blog posts or create pages with Markdown. Need more complexity? Create HTML or PHP files. +- **Markdown & Beyond**: Write blog posts or create pages with Markdown. Need more complexity? Create HTML or PHP files. -* **Efficient Deployment**: Build process visits each PHP and markdown page, saves their HTML, and deploys to GitHub +- **Efficient Deployment**: Build process visits each PHP and markdown page, saves their HTML, and deploys to GitHub Pages. -* **Instant Local Preview**: There is an integrated docker-based local Nginx & PHP server, just run `make dev-server` -to Visualize your changes locally by just refreshing the page without a build process. - +- **Instant Local Preview**: There is an integrated docker-based local Nginx & PHP server, just run `make dev-server` + to Visualize your changes locally by just refreshing the page without a build process. ## Customisation of your site -* Update the `config.json` at root, and `favicon-96.jpg` `site-icon.jpg` `site-icon-big.jpg` at `./assets/images` -* Pages: see examples in `./pages`. Page URLs are derived from the file name. `my-post.md` will be `yoursite. - com/my-post`. +- Update the `config.json` at root, and `favicon-96.jpg` `site-icon.jpg` `site-icon-big.jpg` at `./assets/images` + +- Pages: see examples in `./pages`. Page URLs are derived from the file name. `my-post.md` will be `yoursite. +com/my-post`. -* Blog Posts: see examples in `./posts`. Post URLs are derived from `slug` key in the front matter. Blog post files - start with an id e.g. 2_some_title.md and IDs are used to sort them in descending order. It's a string comparison +- Blog Posts: see examples in `./posts`. Post URLs are derived from `slug` key in the front matter. Blog post files + start with an id e.g. 2_some_title.md and IDs are used to sort them in descending order. It's a string comparison sort, not numeric. -* Layout changes: see `./layout` directory. +- Layout changes: see `./layout` directory. -* Open file `./layout/footer.php` to add your tracking code like Google Analytics, Matomo (Piwik), etc. - * If using advanced analytics, add a GDPR banner, or use analytics with anonymisation. See my blog post about - more: https://www.atasasmaz.com/p/gdpr-friendly-analytics +- Open file `./layout/footer.php` to add your tracking code like Google Analytics, Matomo (Piwik), etc. -* CSS changes: `less` is used to generate `css` files, see `./assets/styles` directory. - * Check `.github/workflows/build-and-deploy.yml` and remove line pointing to the `.less` file if you don't want to + - If using advanced analytics, add a GDPR banner, or use analytics with anonymisation. See my blog post about + more: https://www.atasasmaz.com/p/gdpr-friendly-analytics + +- CSS changes: `less` is used to generate `css` files, see `./assets/styles` directory. + - Check `.github/workflows/build-and-deploy.yml` and remove line pointing to the `.less` file if you don't want to LESS and use good old CSS. ## Having custom PHP files to HTML -You can create any .php at root or any sub-dir. `./layout`, `post.php` and `page.php` are excluded from individual +You can create any .php at root or any sub-dir. `./layout`, `post.php` and `page.php` are excluded from individual PHP to HTML generation. `./my-custom.php` will be `yoursite.com/my-custom` @@ -82,34 +86,38 @@ Omit `.php` extensions in the URLs and links, but keep them in the actual files. ## Local Development Environment -You can spin up the docker container and let it serve the PHP site locally, without a build process. You need to +You can spin up the docker container and let it serve the PHP site locally, without a build process. You need to have `docker` installed on your machine. `cd` into the project directory run: + ``` composer update make dev-server ``` -Alternatively, if you don't have `make` installed, you can run below, and adjust the port `8001` to your liking: +Alternatively, if you don't have `make` installed, you can run below, and adjust the port `8002` to your liking: + ``` -docker run --rm -it --entrypoint /dev-server-entrypoint.sh -p 8001:80 \ +docker run --rm -it --entrypoint /dev-server-entrypoint.sh -p 8002:80 \ -v $(pwd):/workspace ghcr.io/atas/ssg-builder:latest ``` -Your local php site will be running at **http://localhost:8001** with instant updates on page refresh, as PHP does. +Your local php site will be running at **http://localhost:8002** with instant updates on page refresh, as PHP does. ## Keep in touch with this repo's future updates -* Create your empty repo on GitHub with nothing in it, nothing. -* Clone this repo to your local. -* `cd` into this repo and run +- Create your empty repo on GitHub with nothing in it, nothing. +- Clone this repo to your local. +- `cd` into this repo and run + ``` git remote add upstream git@github.com:atas/ssg.git git checkout -b updates-from-upstream git fetch upstream +git checkout main git merge upstream/main git push ``` @@ -120,6 +128,6 @@ Then create a pull request from `updates-from-upstream` branch to `main` branch ### Pagination for posts -I am a fan of continuous scrolling and not numbered pages. We can implement continuous scrolling on the homepage but -I can't imagine if it can be helpful for sites with less than 100 posts. Even after 100 posts, it should not -be a big problem for the page to be rendered. I am open for suggestions though. +I am a fan of continuous scrolling and not numbered pages. We can implement continuous scrolling on the homepage but +I can't imagine if it can be helpful for sites with less than 100 posts. Even after 100 posts, it should not +be a big problem for the page to be rendered. I am open for suggestions though.