From 85f2c8d0d69ac0195bf6a20e396077dee0e9aefa Mon Sep 17 00:00:00 2001 From: Bradley Taunt Date: Fri, 19 Jan 2024 13:19:41 -0500 Subject: Initial commit for new cgit platform --- .build.yml | 12 ++ LICENSE | 8 ++ README.md | 19 +++ _config.sh | 24 ++++ _footer.html | 9 ++ _header.html | 9 ++ _output/blog/community-patch.html | 86 +++++++++++++ _output/blog/default-styles.html | 162 ++++++++++++++++++++++++ _output/blog/index.html | 23 ++++ _output/blog/pblog-intro.html | 185 ++++++++++++++++++++++++++++ _output/blog/pblog-launch.html | 54 ++++++++ _output/blog/small-patch.html | 72 +++++++++++ _output/feed.xml | 252 ++++++++++++++++++++++++++++++++++++++ _output/index.html | 178 +++++++++++++++++++++++++++ _output/media/pb-sandwich.svg | 14 +++ _output/media/pbj.svg | 173 ++++++++++++++++++++++++++ _output/rss.xsl | 66 ++++++++++ _output/style.css | 50 ++++++++ _output/tweaks.html | 191 +++++++++++++++++++++++++++++ makefile | 12 ++ media/pb-sandwich.svg | 14 +++ media/pbj.svg | 173 ++++++++++++++++++++++++++ pages/index.md | 88 +++++++++++++ pages/tweaks.md | 97 +++++++++++++++ pblog.sh | 84 +++++++++++++ posts/community-patch.md | 36 ++++++ posts/default-styles.md | 61 +++++++++ posts/pblog-intro.md | 96 +++++++++++++++ posts/pblog-launch.md | 11 ++ posts/small-patch.md | 27 ++++ rss.xsl | 66 ++++++++++ style.css | 50 ++++++++ 32 files changed, 2402 insertions(+) create mode 100644 .build.yml create mode 100644 LICENSE create mode 100644 README.md create mode 100644 _config.sh create mode 100644 _footer.html create mode 100644 _header.html create mode 100644 _output/blog/community-patch.html create mode 100644 _output/blog/default-styles.html create mode 100644 _output/blog/index.html create mode 100644 _output/blog/pblog-intro.html create mode 100644 _output/blog/pblog-launch.html create mode 100644 _output/blog/small-patch.html create mode 100644 _output/feed.xml create mode 100644 _output/index.html create mode 100644 _output/media/pb-sandwich.svg create mode 100644 _output/media/pbj.svg create mode 100644 _output/rss.xsl create mode 100644 _output/style.css create mode 100644 _output/tweaks.html create mode 100644 makefile create mode 100644 media/pb-sandwich.svg create mode 100644 media/pbj.svg create mode 100644 pages/index.md create mode 100644 pages/tweaks.md create mode 100644 pblog.sh create mode 100644 posts/community-patch.md create mode 100644 posts/default-styles.md create mode 100644 posts/pblog-intro.md create mode 100644 posts/pblog-launch.md create mode 100644 posts/small-patch.md create mode 100644 rss.xsl create mode 100644 style.css diff --git a/.build.yml b/.build.yml new file mode 100644 index 0000000..f830d84 --- /dev/null +++ b/.build.yml @@ -0,0 +1,12 @@ +image: debian/stable +oauth: pages.sr.ht/PAGES:RW +environment: + site: pblog.bt.ht +sources: + - https://git.sr.ht/~bt/pblog +tasks: +- package: | + cd pblog/_output + tar -cvz . > ../../site.tar.gz +- upload: | + acurl -f https://pages.sr.ht/publish/$site -Fcontent=@site.tar.gz \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b9c199c --- /dev/null +++ b/LICENSE @@ -0,0 +1,8 @@ +ISC License: + +Copyright (c) 2004-2010 by Internet Systems Consortium, Inc. ("ISC") +Copyright (c) 1995-2003 by Internet Software Consortium + +Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..421494d --- /dev/null +++ b/README.md @@ -0,0 +1,19 @@ +# pblog + +Pandoc static blog generator + +[https://pblog.btxx.org](https://pblog.btxx.org) + +## Getting Started + +You can always read through the up-to-date article: [Introducing pblog](https://pblog.btxx.org/blog/pblog-intro.html) + +But very basic steps: + +1. Install dependencies +2. Write posts in the `posts` directory +3. Write pages in the `pages` directory +4. Build the site +5. Upload your `_output` folder to your web host + +Enjoy! diff --git a/_config.sh b/_config.sh new file mode 100644 index 0000000..2558aa1 --- /dev/null +++ b/_config.sh @@ -0,0 +1,24 @@ +#!/bin/sh + +# Site specific settings +################################################################################### +DOMAIN="https://pblog.btxx.org" +TITLE="pblog" +DESCRIPTION="Pandoc static blog generator" +COPYRIGHT="Copyright 2022, Bradley Taunt" +AUTHOR="bt@btxx.org (Bradley Taunt)" +OS="Linux" # "Linux" for Linux, "BSD" for BSD Systems (including MacOS) +HTML_LANG="en_US" # Your document (HTML) language setting + +# Blog structure settings (most users should use these defaults) +################################################################################### +TOC=true +SYNTAX=true +PAGES_DIR="pages/" +POSTS_DIR="posts/" +PAGES=$(find $PAGES_DIR -type f) +POSTS=$(find $POSTS_DIR -type f) +WEB_HTML="blog/" +OUTPUT="_output/" +TIME="01:00:00 EST" +TTL="60" diff --git a/_footer.html b/_footer.html new file mode 100644 index 0000000..e6eebe8 --- /dev/null +++ b/_footer.html @@ -0,0 +1,9 @@ + + + + diff --git a/_header.html b/_header.html new file mode 100644 index 0000000..67e2122 --- /dev/null +++ b/_header.html @@ -0,0 +1,9 @@ + + + +
diff --git a/_output/blog/community-patch.html b/_output/blog/community-patch.html new file mode 100644 index 0000000..b6f4dfa --- /dev/null +++ b/_output/blog/community-patch.html @@ -0,0 +1,86 @@ + + + + + + + First Community Patch & Tweaks + + + + + + + + +
+
+

First Community Patch & Tweaks

+

Fri, 15 Jul 2022

+
+ +

pblog has received its first community patch! By “community” I mean someone other than myself has helped make this blog generator even better. So special thanks to Matthew Graybosch for contributing to this humble project and patching in some solid quality of life improvements.

+

This is why open source is great: smarter people can help fix your mashed-up spaghetti code!

+

The Changes

+
    +
  1. Both pages and posts now generated Table of Contents by default +
      +
    • You have the ability to disable this site-wide in the pblog config
      • +
    2. +
  2. Ability to disable Pandoc generated syntax highlighting
    3. +
  3. xsltproc will now generate HTML5 and include the RSS feed description under the title +
    4. +
  4. New metadata variable (HTML_LANG) in the pblog.sh config
    5. +
  5. Generated pages and posts now have “Table of Contents” by default +
      +
    • This can be disabled in individual files with toc: false
      • +
    6. +
  6. Cleaned up redundant find statements
    7. +
+

Some Features Left Behind…

+

Also suggested in this patch was the addition of more advanced image manipulation via ImageMagick. This additional feature was pretty great from my testing but I felt as though adding an extra dependency and slightly more complex settings to pblog was moving things further from simplicity.

+

BUT - that doesn’t mean you can’t take this great feature with you!

+

Introducing “Tweaks”

+

I feel that pblog should always remain as simple as possible at the core. Let people get something up-and-running with the least amount of friction as possible. But I know that some users might want to squeeze just a little bit more out of it. This is where the new Tweaks section comes in.

+

Feel free to check out the official Tweaks page and don’t be afraid to add your own by opening a patch-set!

+

That’s all for now, thanks for reading!

+

– Brad

+
+ + +
+
+
+

Powered by pblog
+ Made with ♥ for a simpler web.

+
+ + diff --git a/_output/blog/default-styles.html b/_output/blog/default-styles.html new file mode 100644 index 0000000..e207ff1 --- /dev/null +++ b/_output/blog/default-styles.html @@ -0,0 +1,162 @@ + + + + + + + New Default Styling and 2x Faster! + + + + + + + + +
+
+

New Default Styling and 2x Faster!

+

Wed, 27 Jul 2022

+
+ +

If it wasn’t already obvious, this project has received a minor styling overhaul. But looks weren’t the only thing updated with this latest patch.

+

The total build process time is now two times faster!

+

Keep reading for more details.

+

The Default “Theme”

+

The styling changes aren’t anything ground breaking. They simply center the main content and add a little more visual separation of the content and backdrop. Again, you can customize pblog as you see fit, but having a sane default is always nice.

+

New Config Setup

+

Since updates and performance fixes might continue to come through in the future, I didn’t want to make users play around with their default configuration every single time. Now, all main configuration is handled in the new _config.sh file.

+
#!/bin/sh
+
+# Site specific settings
+###################################################################################
+DOMAIN="https://pblog.bt.ht"
+TITLE="pblog"
+DESCRIPTION="Pandoc static blog generator"
+COPYRIGHT="Copyright 2022, Bradley Taunt"
+AUTHOR="brad@bt.ht (Bradley Taunt)"
+OS="Linux" # "Linux" for Linux, "BSD" for BSD Systems (including MacOS)
+HTML_LANG="en_US" # Your document (HTML) language setting
+
+# Blog structure settings (most users should use these defaults)
+###################################################################################
+TOC=true
+SYNTAX=true
+PAGES_DIR="pages/"
+POSTS_DIR="posts/"
+PAGES=$(find $PAGES_DIR -type f)
+POSTS=$(find $POSTS_DIR -type f)
+WEB_HTML="blog/"
+OUTPUT="_output/"
+TIME="01:00:00 EST"
+TTL="60"
+

Feels cleaner already, right?

+

Cutting the Build Time in Half

+

I must give big kudos to Matthew Graybosch for inspiring this pretty big improvement. After some discussion over emails we both agreed that it seemed overkill to render the blog content twice (once for the XML feed itself and then again for all posts listed under blog). Performance wasn’t the initial goal when I first launched this project, but now that the dust has settled it seemed appropriate to go back and fix some things.

+

pblog now only needs to render the blog posts found in the posts directory once. It still produces semantic XML and keeps the webview versions of the articles looking solid. Overall I’m pretty happy with this little improvement - it should pretty noticeable on projects rendering many posts.

+

Far From Perfect

+

This project is still very much in it’s infancy. So if you notice something odd or broken in your own testing, please don’t hesitate to open a patch or simply bring up the issue!

+

Thanks for reading,

+

– Brad

+
+ + +
+
+
+

Powered by pblog
+ Made with ♥ for a simpler web.

+
+ + diff --git a/_output/blog/index.html b/_output/blog/index.html new file mode 100644 index 0000000..dbf4f3d --- /dev/null +++ b/_output/blog/index.html @@ -0,0 +1,23 @@ + + +pblog

pblog

Pandoc static blog generator

Wed, 27 Jul 2022 01:00:00 ESTNew Default Styling and 2x Faster!Fri, 15 Jul 2022 01:00:00 ESTFirst Community Patch & TweaksFri, 08 Jul 2022 01:00:00 ESTIncludes, rsync and Variables - Oh My!Mon, 04 Jul 2022 01:00:00 ESTIntroducing pblogThu, 30 Jun 2022 01:00:00 ESTAnnouncing pblog diff --git a/_output/blog/pblog-intro.html b/_output/blog/pblog-intro.html new file mode 100644 index 0000000..86dea87 --- /dev/null +++ b/_output/blog/pblog-intro.html @@ -0,0 +1,185 @@ + + + + + + + Introducing pblog + + + + + + + + +
+
+

Introducing pblog

+

Mon, 04 Jul 2022

+
+ +

This article is a living document. It will always have the most up-to-date information on getting started with pblog.

+

Last Updated: July 27, 2022

+
+

Although this project was already announced a couple days ago, I thought it might be best to actually breakdown pblog into greater detail.

+

Enough chit-chat, let’s get into it!

+

Main Goal

+

The entire purpose of pblog is to be as bare-bones as possible, while still maintaining a pleasant writing workflow. Users write their posts and pages in Markdown - pblog handles everything else:

+
    +
  • Posts and pages generated via Pandoc with minimal CSS
    • +
  • RSS feed at feed.xml
    • +
  • Generated blog listing at blog/index.html
    • +
  • Browser-styled XML (in supported browsers)
    • +
+

Site Structure

+

After you’ve cloned the official pblog repo on sourcehut, the next thing you should do is edit the main _config.sh file in the root directory. This will give you a better understanding of how everything is built.

+

Once generated, pblog structures the final website files as such:

+
_output/
+    |__blog/
+        |__index.html
+        |__blog-post-example.html
+    |__media/
+    |__feed.xml
+    |__index.html
+    |__rss.xsl
+    |__style.css
+

This structure is completely customizable by simply editing the _config.sh file (if you so desire).

+

Headers and Footers

+

By default pblog will add the header and footer includes to every individual post and page. To edit these, simply open the _header.html and _footer.html files respectively.

+

Important: To avoid rendering issues DO NOT remove the included article opening and closing tags within those files. Everything else you can edit, remove, etc.

+

Posts and Pages

+

Posts and pages are written via Markdown inside the posts and pages folders respectively.

+

Individual posts require the following headers (take note of the date format):

+
---
+title: Blog Title
+date: Mon, 04 Jul 2022
+---
+

while individual pages only require a title:

+
---
+title: Page Title
+---
+

This makes for an easier switch over from other SSG platforms like Jekyll or Hugo.

+

The Build Process

+

The main variables at the top of the pblog.sh file need to edited with your own details before generating your website. Those variables are fairly self-explanatory and simple to edit.

+

All you need to do now is run make (or make serve if you’re looking to test locally) and you’re done. Your website should now be fully generated inside the include _output directory. For quick reference:

+
    +
  1. pblog converts your Markdown posts into two variations of HTML +
      +
    • One is used specifically for rendering itself inside the RSS feed
      • +
    • The other is used for linking in a browser
      • +
    2. +
  2. Next, pblog converts your Markdown pages into HTML
    3. +
  3. All of these generated HTML files are then moved to the _output folder
    4. +
+

pblog is also smart enough to automatically generate a main blog list directory for you. This index.html file is placed inside the _output/blog folder on build. You can see an example of the blog list on this very website.

+

Uploading to the WWW

+

Those with more experience will probably lean towards using a utility like rsync to sync the contents of their _output folder with their web server. For those with less experience, I recommend using something like Netlify Drop to make things as friction-less as possible.

+

Wrapping Up

+

There isn’t much else to say. pblog is as static or flexible as you chose it to be. If you have any ideas on how to improve things or come across any bugs, please open a ticket or PR on the official repo.

+

Thanks and happy blogging with pblog!

+
+ + +
+
+
+

Powered by pblog
+ Made with ♥ for a simpler web.

+
+ + diff --git a/_output/blog/pblog-launch.html b/_output/blog/pblog-launch.html new file mode 100644 index 0000000..754aff0 --- /dev/null +++ b/_output/blog/pblog-launch.html @@ -0,0 +1,54 @@ + + + + + + + Announcing pblog + + + + + + + + +
+
+

Announcing pblog

+

Thu, 30 Jun 2022

+
+

It’s time to celebrate! The official launch of pblog happened today.

+

There isn’t much else to say. All details and instructions on how to start your own pblog can be found on the main homepage for this project.

+

Thanks for reading!

+
+ + +
+
+
+

Powered by pblog
+ Made with ♥ for a simpler web.

+
+ + diff --git a/_output/blog/small-patch.html b/_output/blog/small-patch.html new file mode 100644 index 0000000..e80c02a --- /dev/null +++ b/_output/blog/small-patch.html @@ -0,0 +1,72 @@ + + + + + + + Includes, rsync and Variables - Oh My! + + + + + + + + +
+
+

Includes, rsync and Variables - Oh My!

+

Fri, 08 Jul 2022

+
+ +

Even though pblog was just launched a week ago, it has since been updated with some nice quality-of-life improvements.

+ +

A new variable was added to the main pblog.sh configuration file called INC_HEAD_FOOT. By default this is set to true and simply pulls in two HTML files:

+
    +
  • _header.html: all content within is placed directly after the opening body tag
    • +
  • _footer.html: all content within is placed directly before the closing body tag
    • +
+

These includes are added to every outputted file from inside both the posts and pages directories on build.

+

Syncing Changes with rsync

+

Although it adds another dependency to the project, I believe utilizing rsync for the generated files is far better then nuking the directory from orbit each time. This also provides a cleaner experience for users syncing their _output directory with their web server of choice.

+

On the Horizon…

+

My plan was to also tackle the issue of “auto rebuilds” when running pblog locally. This became more of a headache than I initially estimated - so it was dropped from this patch. My hope is to get something up-and-running in the near future, while avoiding the inclusion of yet another major dependency. Anyone more experienced than myself in the ways of “auto rebuilds” is free to open a patch if they so desire!

+

Thanks for your interest in these minor updates!

+

P.S. Don’t forget - if your website runs on pblog be sure to reach out and get it featured on the homepage!

+
+ + +
+
+
+

Powered by pblog
+ Made with ♥ for a simpler web.

+
+ + diff --git a/_output/feed.xml b/_output/feed.xml new file mode 100644 index 0000000..2b0c5eb --- /dev/null +++ b/_output/feed.xml @@ -0,0 +1,252 @@ + + + + + pblog + https://pblog.bt.ht + Pandoc static blog generator + Copyright 2022, Bradley Taunt + 60 + + Fri, 15 Jul 2022 01:00:00 EST + 2022/07/15/5 + First Community Patch & Tweaks + https://pblog.bt.ht/blog/community-patch.html + +

First Community Patch & Tweaks

+

Fri, 15 Jul 2022

+ + +

pblog has received its first community patch! By “community” I mean someone other than myself has helped make this blog generator even better. So special thanks to Matthew Graybosch for contributing to this humble project and patching in some solid quality of life improvements.

+

This is why open source is great: smarter people can help fix your mashed-up spaghetti code!

+

The Changes

+
    +
  1. Both pages and posts now generated Table of Contents by default +
      +
    • You have the ability to disable this site-wide in the pblog config
      • +
    2. +
  2. Ability to disable Pandoc generated syntax highlighting
    3. +
  3. xsltproc will now generate HTML5 and include the RSS feed description under the title +
    4. +
  4. New metadata variable (HTML_LANG) in the pblog.sh config
    5. +
  5. Generated pages and posts now have “Table of Contents” by default +
      +
    • This can be disabled in individual files with toc: false
      • +
    6. +
  6. Cleaned up redundant find statements
    7. +
+

Some Features Left Behind…

+

Also suggested in this patch was the addition of more advanced image manipulation via ImageMagick. This additional feature was pretty great from my testing but I felt as though adding an extra dependency and slightly more complex settings to pblog was moving things further from simplicity.

+

BUT - that doesn’t mean you can’t take this great feature with you!

+

Introducing “Tweaks”

+

I feel that pblog should always remain as simple as possible at the core. Let people get something up-and-running with the least amount of friction as possible. But I know that some users might want to squeeze just a little bit more out of it. This is where the new Tweaks section comes in.

+

Feel free to check out the official Tweaks page and don’t be afraid to add your own by opening a patch-set!

+

That’s all for now, thanks for reading!

+

– Brad

]]> + brad@bt.ht (Bradley Taunt) + https://pblog.bt.ht/blog/community-patch.html + + + Wed, 27 Jul 2022 01:00:00 EST + 2022/07/27/3 + New Default Styling and 2x Faster! + https://pblog.bt.ht/blog/default-styles.html + +

New Default Styling and 2x Faster!

+

Wed, 27 Jul 2022

+ + +

If it wasn’t already obvious, this project has received a minor styling overhaul. But looks weren’t the only thing updated with this latest patch.

+

The total build process time is now two times faster!

+

Keep reading for more details.

+

The Default “Theme”

+

The styling changes aren’t anything ground breaking. They simply center the main content and add a little more visual separation of the content and backdrop. Again, you can customize pblog as you see fit, but having a sane default is always nice.

+

New Config Setup

+

Since updates and performance fixes might continue to come through in the future, I didn’t want to make users play around with their default configuration every single time. Now, all main configuration is handled in the new _config.sh file.

+
#!/bin/sh
+
+# Site specific settings
+###################################################################################
+DOMAIN="https://pblog.bt.ht"
+TITLE="pblog"
+DESCRIPTION="Pandoc static blog generator"
+COPYRIGHT="Copyright 2022, Bradley Taunt"
+AUTHOR="brad@bt.ht (Bradley Taunt)"
+OS="Linux" # "Linux" for Linux, "BSD" for BSD Systems (including MacOS)
+HTML_LANG="en_US" # Your document (HTML) language setting
+
+# Blog structure settings (most users should use these defaults)
+###################################################################################
+TOC=true
+SYNTAX=true
+PAGES_DIR="pages/"
+POSTS_DIR="posts/"
+PAGES=$(find $PAGES_DIR -type f)
+POSTS=$(find $POSTS_DIR -type f)
+WEB_HTML="blog/"
+OUTPUT="_output/"
+TIME="01:00:00 EST"
+TTL="60"
+

Feels cleaner already, right?

+

Cutting the Build Time in Half

+

I must give big kudos to Matthew Graybosch for inspiring this pretty big improvement. After some discussion over emails we both agreed that it seemed overkill to render the blog content twice (once for the XML feed itself and then again for all posts listed under blog). Performance wasn’t the initial goal when I first launched this project, but now that the dust has settled it seemed appropriate to go back and fix some things.

+

pblog now only needs to render the blog posts found in the posts directory once. It still produces semantic XML and keeps the webview versions of the articles looking solid. Overall I’m pretty happy with this little improvement - it should pretty noticeable on projects rendering many posts.

+

Far From Perfect

+

This project is still very much in it’s infancy. So if you notice something odd or broken in your own testing, please don’t hesitate to open a patch or simply bring up the issue!

+

Thanks for reading,

+

– Brad

]]> + brad@bt.ht (Bradley Taunt) + https://pblog.bt.ht/blog/default-styles.html + + + Mon, 04 Jul 2022 01:00:00 EST + 2022/07/04/1 + Introducing pblog + https://pblog.bt.ht/blog/pblog-intro.html + +

Introducing pblog

+

Mon, 04 Jul 2022

+ + +

This article is a living document. It will always have the most up-to-date information on getting started with pblog.

+

Last Updated: July 27, 2022

+
+

Although this project was already announced a couple days ago, I thought it might be best to actually breakdown pblog into greater detail.

+

Enough chit-chat, let’s get into it!

+

Main Goal

+

The entire purpose of pblog is to be as bare-bones as possible, while still maintaining a pleasant writing workflow. Users write their posts and pages in Markdown - pblog handles everything else:

+
    +
  • Posts and pages generated via Pandoc with minimal CSS
    • +
  • RSS feed at feed.xml
    • +
  • Generated blog listing at blog/index.html
    • +
  • Browser-styled XML (in supported browsers)
    • +
+

Site Structure

+

After you’ve cloned the official pblog repo on sourcehut, the next thing you should do is edit the main _config.sh file in the root directory. This will give you a better understanding of how everything is built.

+

Once generated, pblog structures the final website files as such:

+
_output/
+    |__blog/
+        |__index.html
+        |__blog-post-example.html
+    |__media/
+    |__feed.xml
+    |__index.html
+    |__rss.xsl
+    |__style.css
+

This structure is completely customizable by simply editing the _config.sh file (if you so desire).

+

Headers and Footers

+

By default pblog will add the header and footer includes to every individual post and page. To edit these, simply open the _header.html and _footer.html files respectively.

+

Important: To avoid rendering issues DO NOT remove the included article opening and closing tags within those files. Everything else you can edit, remove, etc.

+

Posts and Pages

+

Posts and pages are written via Markdown inside the posts and pages folders respectively.

+

Individual posts require the following headers (take note of the date format):

+
---
+title: Blog Title
+date: Mon, 04 Jul 2022
+---
+

while individual pages only require a title:

+
---
+title: Page Title
+---
+

This makes for an easier switch over from other SSG platforms like Jekyll or Hugo.

+

The Build Process

+

The main variables at the top of the pblog.sh file need to edited with your own details before generating your website. Those variables are fairly self-explanatory and simple to edit.

+

All you need to do now is run make (or make serve if you’re looking to test locally) and you’re done. Your website should now be fully generated inside the include _output directory. For quick reference:

+
    +
  1. pblog converts your Markdown posts into two variations of HTML +
      +
    • One is used specifically for rendering itself inside the RSS feed
      • +
    • The other is used for linking in a browser
      • +
    2. +
  2. Next, pblog converts your Markdown pages into HTML
    3. +
  3. All of these generated HTML files are then moved to the _output folder
    4. +
+

pblog is also smart enough to automatically generate a main blog list directory for you. This index.html file is placed inside the _output/blog folder on build. You can see an example of the blog list on this very website.

+

Uploading to the WWW

+

Those with more experience will probably lean towards using a utility like rsync to sync the contents of their _output folder with their web server. For those with less experience, I recommend using something like Netlify Drop to make things as friction-less as possible.

+

Wrapping Up

+

There isn’t much else to say. pblog is as static or flexible as you chose it to be. If you have any ideas on how to improve things or come across any bugs, please open a ticket or PR on the official repo.

+

Thanks and happy blogging with pblog!

]]> + brad@bt.ht (Bradley Taunt) + https://pblog.bt.ht/blog/pblog-intro.html + + + Thu, 30 Jun 2022 01:00:00 EST + 2022/06/30/4 + Announcing pblog + https://pblog.bt.ht/blog/pblog-launch.html + +

Announcing pblog

+

Thu, 30 Jun 2022

+ +

It’s time to celebrate! The official launch of pblog happened today.

+

There isn’t much else to say. All details and instructions on how to start your own pblog can be found on the main homepage for this project.

+

Thanks for reading!

]]> + brad@bt.ht (Bradley Taunt) + https://pblog.bt.ht/blog/pblog-launch.html + + + Fri, 08 Jul 2022 01:00:00 EST + 2022/07/08/5 + Includes, rsync and Variables - Oh My! + https://pblog.bt.ht/blog/small-patch.html + +

Includes, rsync and Variables - Oh My!

+

Fri, 08 Jul 2022

+ + +

Even though pblog was just launched a week ago, it has since been updated with some nice quality-of-life improvements.

+ +

A new variable was added to the main pblog.sh configuration file called INC_HEAD_FOOT. By default this is set to true and simply pulls in two HTML files:

+
    +
  • _header.html: all content within is placed directly after the opening body tag
    • +
  • _footer.html: all content within is placed directly before the closing body tag
    • +
+

These includes are added to every outputted file from inside both the posts and pages directories on build.

+

Syncing Changes with rsync

+

Although it adds another dependency to the project, I believe utilizing rsync for the generated files is far better then nuking the directory from orbit each time. This also provides a cleaner experience for users syncing their _output directory with their web server of choice.

+

On the Horizon…

+

My plan was to also tackle the issue of “auto rebuilds” when running pblog locally. This became more of a headache than I initially estimated - so it was dropped from this patch. My hope is to get something up-and-running in the near future, while avoiding the inclusion of yet another major dependency. Anyone more experienced than myself in the ways of “auto rebuilds” is free to open a patch if they so desire!

+

Thanks for your interest in these minor updates!

+

P.S. Don’t forget - if your website runs on pblog be sure to reach out and get it featured on the homepage!

]]> + brad@bt.ht (Bradley Taunt) + https://pblog.bt.ht/blog/small-patch.html + + + diff --git a/_output/index.html b/_output/index.html new file mode 100644 index 0000000..ce823c6 --- /dev/null +++ b/_output/index.html @@ -0,0 +1,178 @@ + + + + + + + pblog + + + + + + + + +
+
+

pblog

+
+

Peanut butter sandwich

+

Pandoc static blog generator

+

pblog comes packed with an incredible list of features:

+
    +
  • 5-second configuration
    • +
  • Write all your posts and pages in Markdown
    • +
  • Valid RSS 2.0 feed (customized design too!)
    • +
+

and it also doesn’t ship with a lot of other features:

+
    +
  • No advanced template layouts
    • +
  • No themes
    • +
  • No categories / tagging systems
    • +
  • No comments
    • +
  • No auto rebuilds for local testing
    • +
+

But you can add these things yourself with a little know-how and patience! The goal of pblog is to remain as bare-bones as possible, so these “extras” are left out intentionally.

+

Live Demo

+

This very website is a live demo! Mind blowing, right? Take a look at the automated blog list to see some blog posts.

+

Requirements

+

On MacOS / BSD Systems

+ +

On Linux

+ +

Getting Started

+
    +
  1. Clone the project repo: https://git.sr.ht/~bt/pblog
    2. +
  2. Edit the variables at the top of the pblog.sh file
    3. +
  3. !! Pay close attention to the OS variable to set your correct operating system !!
    4. +
  4. Edit the posts in posts and pages in pages to your own
    5. +
  5. Run make from the root directory
    6. +
  6. Upload the contents of the _output folder to your server
    7. +
  7. Profit!!!
    8. +
+

For a more in-depth look, take a look at the article Introducing pblog

+

Base Settings

+

Table of Contents

+

By default pblog ships with TOC (Table of Contents) enabled. You can disable this on each individual page or post by editing the TOCvariable in pblog.sh to false:

+
TOC: false
+

Code Highlighting

+

pblog uses the standard syntax highlighting provided with Pandoc. To disable this, set the SYNTAX variable to false in pblog.sh:

+
SYNTAX: false
+

Extras

+
    +
  • Add all media files (images, videos, etc.) under the media folder
    • +
  • Customize the look of your blog by editing the included style.css
    • +
  • Looking for fancier image manipulation? Take a look at this detailed post to get setup
    • +
+

You can share your pblog websites by emailing me at the address listed below and I’ll add them here.

+

brad at bt {dot} ht

+

Websites Using pblog

+ +
+ + +
+
+
+

Powered by pblog
+ Made with ♥ for a simpler web.

+
+ + diff --git a/_output/media/pb-sandwich.svg b/_output/media/pb-sandwich.svg new file mode 100644 index 0000000..c133117 --- /dev/null +++ b/_output/media/pb-sandwich.svg @@ -0,0 +1,14 @@ + + + + pb-sandwich + Created with Sketch. + + + + + + + + + \ No newline at end of file diff --git a/_output/media/pbj.svg b/_output/media/pbj.svg new file mode 100644 index 0000000..1714983 --- /dev/null +++ b/_output/media/pbj.svg @@ -0,0 +1,173 @@ + + + + + + + + + + PBJ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + Openclipart + + + PBJ + 2010-10-04T20:14:18 + Outlines of an uppercase and lowercase letter j, with a jar for coloring. Typeface is Let's Trace (public domain). + https://openclipart.org/detail/88633/j-is-for-jar-by-mazeo + + + mazeo + + + + + alphabet + coloring book + colouring book + jar + letter J + remix + + + + + + + + + + + \ No newline at end of file diff --git a/_output/rss.xsl b/_output/rss.xsl new file mode 100644 index 0000000..2b54fe5 --- /dev/null +++ b/_output/rss.xsl @@ -0,0 +1,66 @@ + + + + + + + + <xsl:value-of select="/rss/channel/title" /> + + + + + + + + + + + + + +
+

+

+ +

+
+ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/_output/style.css b/_output/style.css new file mode 100644 index 0000000..6c1cca6 --- /dev/null +++ b/_output/style.css @@ -0,0 +1,50 @@ +html { + background:#f9f9f9; +} + +body { + background: #fff; + border: 1px solid lightgrey; + margin: 1em auto; + max-width: 75ch; + padding: 10px; + line-height: 1.4; +} + +p code, li code { + border: 1px solid brown; + border-radius: 2px; + color: brown; + padding: 1px 2px; +} +.sourceCode { + overflow: auto; +} + +img { + height: auto; + max-width: 100%; +} + +pre { + background: #f9f9f9; + border: 1px solid lightgrey; + padding: 5px; +} + +#TOC { + border: 1px solid; + position: relative; +} +#TOC:before { + border-bottom: 1px solid; + content: 'Table of Contents'; + display: block; + font-weight: bold; + padding: 5px; + position: relative; +} + +.date { + color: grey; +} diff --git a/_output/tweaks.html b/_output/tweaks.html new file mode 100644 index 0000000..0d61f88 --- /dev/null +++ b/_output/tweaks.html @@ -0,0 +1,191 @@ + + + + + + + Tweaks + + + + + + + + +
+
+

Tweaks

+
+ +

Tweaks Explained

+

“Tweaks” are extra features that are not packaged within the default pblog project. If you have your own tweaks you would like to include, be sure to open a patch.

+
+


+

Magick Images

+

by: Matthew Graybosch

+

This tweak gives you the ability to automatically convert PNG and JPG images to WEBP and AVIF files when used with the picture HTML element.

+

Requirements:

+ +

Then change your base makefile to reflect the following:

+
.SUFFIXES: .png .jpg .webp .avif
+
+.jpg.webp:
+    magick -quality 80 "$<" "$@"
+
+.jpg.avif:
+    magick -quality 80 "$<" "$@"
+
+.png.webp:
+    magick -quality 80 "$<" "$@"
+
+.png.avif:
+    magick -quality 80 "$<" "$@"
+
+JPEGS!=find media/ -name '*.jpg'
+PNGS!=find media/ -name '*.png'
+
+JPEG_WEBP=${JPEGS:.jpg=.webp}
+JPEG_AVIF=${JPEGS:.jpg=.avif}
+
+PNG_WEBP=${PNGS:.png=.webp}
+PNG_AVIF=${PNGS:.png=.avif}
+
+.DEFAULT: build
+
+.PHONY: build
+build: $(JPEG_WEBP) $(JPEG_AVIF) $(PNG_WEBP) $(PNG_AVIF)
+    bash pblog.sh > _output/feed.xml
+    xsltproc _output/feed.xml | tail -n +2 > _output/blog/index.html
+
+serve: build
+    python3 -m http.server --directory _output/
+
+clean:
+    rm _output/* rss/* $(JPEG_WEBP) $(JPEG_AVIF) $(PNG_WEBP) $(PNG_AVIF)
+

That’s it. Enjoy!

+
+


+

Hiding Table of Contents “Heading”

+

by Bradley Taunt

+

By default the include Table of Contents displays a title and styled section. To disable this, simply edit the style.css file and comment out or delete the following:

+
#TOC {
+    border: 1px solid;
+    position: relative;
+}
+#TOC:before {
+    border-bottom: 1px solid;
+    content: 'Table of Contents';
+    display: block;
+    font-weight: bold;
+    padding: 5px;
+    position: relative;
+}
+
+


+

Adding navigation to blog index and RSS feed

+

In order to include any main navigation (or other custom elements for that matter) on the main blog index page and RSS feed.xml, simply edit the rss.xml file in the root directory. Be sure to add your elements / content inside the body tag near the bottom of the page.

+
+ + +
+
+
+

Powered by pblog
+ Made with ♥ for a simpler web.

+
+ + diff --git a/makefile b/makefile new file mode 100644 index 0000000..3e8feee --- /dev/null +++ b/makefile @@ -0,0 +1,12 @@ +.DEFAULT: build + +.PHONY: build +build: + bash pblog.sh > _output/feed.xml + xsltproc _output/feed.xml > _output/blog/index.html + +serve: build + python3 -m http.server --directory _output/ + +clean: + rm _output/* diff --git a/media/pb-sandwich.svg b/media/pb-sandwich.svg new file mode 100644 index 0000000..c133117 --- /dev/null +++ b/media/pb-sandwich.svg @@ -0,0 +1,14 @@ + + + + pb-sandwich + Created with Sketch. + + + + + + + + + \ No newline at end of file diff --git a/media/pbj.svg b/media/pbj.svg new file mode 100644 index 0000000..1714983 --- /dev/null +++ b/media/pbj.svg @@ -0,0 +1,173 @@ + + + + + + + + + + PBJ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + Openclipart + + + PBJ + 2010-10-04T20:14:18 + Outlines of an uppercase and lowercase letter j, with a jar for coloring. Typeface is Let's Trace (public domain). + https://openclipart.org/detail/88633/j-is-for-jar-by-mazeo + + + mazeo + + + + + alphabet + coloring book + colouring book + jar + letter J + remix + + + + + + + + + + + \ No newline at end of file diff --git a/pages/index.md b/pages/index.md new file mode 100644 index 0000000..c8b5eb2 --- /dev/null +++ b/pages/index.md @@ -0,0 +1,88 @@ +--- +title: pblog +toc: false +--- + +Peanut butter sandwich + +## Pandoc static blog generator + +`pblog` comes packed with an incredible list of features: + +- 5-second configuration +- Write all your posts and pages in Markdown +- Valid RSS 2.0 feed (customized design too!) + +and it also *doesn't* ship with a lot of other features: + +- No advanced template layouts +- No themes +- No categories / tagging systems +- No comments +- No auto rebuilds for local testing + +But you can add these things yourself with a little know-how and patience! The goal of `pblog` is to remain as bare-bones as possible, so these "extras" are left out intentionally. + +## Live Demo + +This very website is a live demo! Mind blowing, right? Take a look at the [automated blog list](/blog) to see some blog posts. + +## Requirements + +#### On MacOS / BSD Systems + +- [rsync](https://linux.die.net/man/1/rsync) +- [coreutils](https://www.gnu.org/software/coreutils/) +- [xsltproc](http://xmlsoft.org/xslt/xsltproc.html) +- [Pandoc](https://pandoc.org/installing.html) + +#### On Linux + +- [rsync](https://linux.die.net/man/1/rsync) +- [xsltproc](http://xmlsoft.org/xslt/xsltproc.html) +- [Pandoc](https://pandoc.org/installing.html) + +## Getting Started + +1. Clone the project repo: [https://git.sr.ht/~bt/pblog](https://git.sr.ht/~bt/pblog) +2. Edit the variables at the top of the `pblog.sh` file +3. **!! Pay close attention to the `OS` variable to set your correct operating system !!** +4. Edit the posts in `posts` and pages in `pages` to your own +5. Run `make` from the root directory +6. Upload the contents of the `_output` folder to your server +7. Profit!!! + +For a more in-depth look, take a look at the article [Introducing pblog](/blog/pblog-intro.html) + +## Base Settings + +#### Table of Contents + +By default `pblog` ships with TOC (Table of Contents) enabled. You can disable this on each individual page or post by editing the `TOC `variable in `pblog.sh` to `false`: + +```yaml +TOC: false +``` + +#### Code Highlighting + +`pblog` uses the standard syntax highlighting provided with Pandoc. To disable this, set the `SYNTAX` variable to `false` in `pblog.sh`: + +```yaml +SYNTAX: false +``` + +## Extras + +- Add all media files (images, videos, etc.) under the `media` folder +- Customize the look of your blog by editing the included `style.css` +- Looking for fancier *image manipulation*? Take a look at [this detailed post to get setup](/tweaks.html) + +You can share your **pblog** websites by emailing me at the address listed below and I'll add them here. + +brad at bt {dot} ht + +## Websites Using `pblog` + +- [pblog.bt.ht](https://pblog.bt.ht) (this site!) +- [ng5p.com](https://www.ng5p.com) diff --git a/pages/tweaks.md b/pages/tweaks.md new file mode 100644 index 0000000..a83e90d --- /dev/null +++ b/pages/tweaks.md @@ -0,0 +1,97 @@ +--- +title: Tweaks +toc: true +--- + +## Tweaks Explained + +"Tweaks" are extra features that are not packaged within the default `pblog` project. If you have your own tweaks you would like to include, be sure to [open a patch](https://git.sr.ht/~bt/pblog). + +--- + +
+ +## Magick Images + +#### by: [Matthew Graybosch](https://matthewgraybosch.com) + +This tweak gives you the ability to automatically convert PNG and JPG images to WEBP and AVIF files when used with the `picture` HTML element. + +**Requirements**: + +- Download and install [ImageMagick](https://imagemagick.org/script/download.php) + +Then change your base `makefile` to reflect the following: + +```bash +.SUFFIXES: .png .jpg .webp .avif + +.jpg.webp: + magick -quality 80 "$<" "$@" + +.jpg.avif: + magick -quality 80 "$<" "$@" + +.png.webp: + magick -quality 80 "$<" "$@" + +.png.avif: + magick -quality 80 "$<" "$@" + +JPEGS!=find media/ -name '*.jpg' +PNGS!=find media/ -name '*.png' + +JPEG_WEBP=${JPEGS:.jpg=.webp} +JPEG_AVIF=${JPEGS:.jpg=.avif} + +PNG_WEBP=${PNGS:.png=.webp} +PNG_AVIF=${PNGS:.png=.avif} + +.DEFAULT: build + +.PHONY: build +build: $(JPEG_WEBP) $(JPEG_AVIF) $(PNG_WEBP) $(PNG_AVIF) + bash pblog.sh > _output/feed.xml + xsltproc _output/feed.xml | tail -n +2 > _output/blog/index.html + +serve: build + python3 -m http.server --directory _output/ + +clean: + rm _output/* rss/* $(JPEG_WEBP) $(JPEG_AVIF) $(PNG_WEBP) $(PNG_AVIF) +``` + +That's it. Enjoy! + +--- + +
+ +## Hiding Table of Contents "Heading" + +#### by [Bradley Taunt](https://tdarb.org) + +By default the include *Table of Contents* displays a title and styled section. To disable this, simply edit the `style.css` file and comment out or delete the following: + +```css +#TOC { + border: 1px solid; + position: relative; +} +#TOC:before { + border-bottom: 1px solid; + content: 'Table of Contents'; + display: block; + font-weight: bold; + padding: 5px; + position: relative; +} +``` + +--- + +
+ +## Adding navigation to blog index and RSS feed + +In order to include any main navigation (or other custom elements for that matter) on the main blog index page and RSS `feed.xml`, simply edit the `rss.xml` file in the root directory. Be sure to add your elements / content inside the `body` tag near the bottom of the page. diff --git a/pblog.sh b/pblog.sh new file mode 100644 index 0000000..26d163c --- /dev/null +++ b/pblog.sh @@ -0,0 +1,84 @@ +#!/bin/sh + +source _config.sh + +################################################################################### +# !WARNING! +# You probably don't need to tweak anything below this line. Edit at your own risk! +################################################################################### + +# Create the $OUTPUT directory if it does not exist yet +mkdir -p $OUTPUT + +if [[ $TOC = true ]] + then + TOC_TOGGLE="--toc"; + else + TOC_TOGGLE=""; +fi + +if [[ $SYNTAX = true ]] + then + SYNTAX_TOGGLE=""; + else + SYNTAX_TOGGLE="--no-highlight"; +fi + +# Create the web browser-focused HTML versions for all posts +for i in $POSTS; do pandoc --css=../style.css --ascii --metadata lang="$HTML_LANG" $TOC_TOGGLE $SYNTAX_TOGGLE --wrap=none -A _footer.html -B _header.html -s $i -o ${i%.*}.html; done; + +rsync $POSTS_DIR*.html $OUTPUT$WEB_HTML; +rm $POSTS_DIR*.html + +# Create the web browser-focused HTML versions for all pages +for i in $PAGES; do pandoc --css=style.css --ascii --metadata lang="$HTML_LANG" $TOC_TOGGLE $SYNTAX_TOGGLE --wrap=none -A _footer.html -B _header.html -s $i -o ${i%.*}.html; done; + +rsync $PAGES_DIR*.html $OUTPUT; +rm $PAGES_DIR*.html + +# Copy XSLT, stylesheet, and media files +rsync rss.xsl $OUTPUT; +rsync style.css $OUTPUT; +rsync -r media $OUTPUT; + +# Remove the default blog index to avoid pulling into the XML feed +rm $OUTPUT$WEB_HTML/index.html + +echo " + + + + $TITLE + $DOMAIN + $DESCRIPTION + $COPYRIGHT + $TTL"; + +for file in $OUTPUT$WEB_HTML*; do + +POST_DATE=$(sed -n 's|^

\([^<]*\)

$|\1|p' $file) +POST_TITLE=$(sed -n 's|^

\([^<]*\)

$|\1|p' $file) +POST_CONTENT=$(sed -n '/
/,/<\/article>/p' $file | sed -e '1s/.*
//' -e '$s/<\/article>.*//') + +if [[ $OS = "BSD" ]] +then + CAT_DATE=$(gdate -d "$(sed -n 's|^

\([^<]*\)

$|\1|p' $file)" +"%Y/%m/%d/%u") + POST_DATE=$(gdate -d "$(sed -n 's|^

\([^<]*\)

$|\1|p' $file)" +"%a, %d %b %Y") +else + CAT_DATE=$(date -d "$(sed -n 's|^

\([^<]*\)

$|\1|p' $file)" +"%Y/%m/%d/%u") + POST_DATE=$(date -d "$(sed -n 's|^

\([^<]*\)

$|\1|p' $file)" +"%a, %d %b %Y") +fi + +echo " + $POST_DATE $TIME + $CAT_DATE + $POST_TITLE + $DOMAIN/$WEB_HTML$(basename ${file}) + + $AUTHOR + $DOMAIN/$WEB_HTML$(basename ${file}) + "; +done + +echo " +"; diff --git a/posts/community-patch.md b/posts/community-patch.md new file mode 100644 index 0000000..2a25b19 --- /dev/null +++ b/posts/community-patch.md @@ -0,0 +1,36 @@ +--- +title: 'First Community Patch & Tweaks' +date: Fri, 15 Jul 2022 +--- + +`pblog` has received its first community patch! By "community" I mean someone other than myself has helped make this blog generator even better. So special thanks to [Matthew Graybosch](https://matthewgraybosch.com/) for contributing to this humble project and patching in some solid quality of life improvements. + +This is why open source is great: smarter people can help fix your mashed-up spaghetti code! + +### The Changes + +1. Both pages and posts now generated *Table of Contents* by default + - You have the ability to disable this site-wide in the `pblog` config +2. Ability to disable Pandoc generated syntax highlighting +3. `xsltproc` will now generate HTML5 and include the RSS feed description under the title + - See it live on the [main RSS XML feed](/feed.xml) +4. New metadata variable (`HTML_LANG`) in the `pblog.sh` config +5. Generated pages and posts now have "Table of Contents" by default + - This can be disabled in individual files with `toc: false` +6. Cleaned up redundant find statements + +### Some Features Left Behind... + +Also suggested in this patch was the addition of more advanced image manipulation via `ImageMagick`. This additional feature was pretty great from my testing but I felt as though adding an extra dependency and *slightly* more complex settings to `pblog` was moving things further from simplicity. + +**BUT** - that doesn't mean you can't take this great feature with you! + +### Introducing "Tweaks" + +I feel that `pblog` should always remain as simple as possible at the core. Let people get something up-and-running with the least amount of friction as possible. But I know that some users might want to squeeze just a *little* bit more out of it. This is where the new **Tweaks** section comes in. + +Feel free to check out the [official Tweaks page](/tweaks.html) and don't be afraid to add your own by opening a patch-set! + +That's all for now, thanks for reading! + +-- Brad \ No newline at end of file diff --git a/posts/default-styles.md b/posts/default-styles.md new file mode 100644 index 0000000..1a09ca7 --- /dev/null +++ b/posts/default-styles.md @@ -0,0 +1,61 @@ +--- +title: New Default Styling and 2x Faster! +date: Wed, 27 Jul 2022 +--- + +If it wasn't already obvious, this project has received a minor styling overhaul. But looks weren't the only thing updated with this latest patch. + +The total build process time is now *two times faster*! + +Keep reading for more details. + +## The Default "Theme" + +The styling changes aren't anything ground breaking. They simply center the main content and add a little more visual separation of the content and backdrop. Again, you can customize `pblog` as you see fit, but having a sane default is always nice. + +## New Config Setup + +Since updates and performance fixes might continue to come through in the future, I didn't want to make users play around with their default configuration every single time. Now, all main configuration is handled in the new `_config.sh` file. + +```sh +#!/bin/sh + +# Site specific settings +################################################################################### +DOMAIN="https://pblog.bt.ht" +TITLE="pblog" +DESCRIPTION="Pandoc static blog generator" +COPYRIGHT="Copyright 2022, Bradley Taunt" +AUTHOR="brad@bt.ht (Bradley Taunt)" +OS="Linux" # "Linux" for Linux, "BSD" for BSD Systems (including MacOS) +HTML_LANG="en_US" # Your document (HTML) language setting + +# Blog structure settings (most users should use these defaults) +################################################################################### +TOC=true +SYNTAX=true +PAGES_DIR="pages/" +POSTS_DIR="posts/" +PAGES=$(find $PAGES_DIR -type f) +POSTS=$(find $POSTS_DIR -type f) +WEB_HTML="blog/" +OUTPUT="_output/" +TIME="01:00:00 EST" +TTL="60" +``` + +Feels cleaner already, right? + +## Cutting the Build Time in Half + +I must give big kudos to [Matthew Graybosch](https://matthewgraybosch.com) for inspiring this pretty big improvement. After some discussion over emails we both agreed that it seemed overkill to render the blog content twice (once for the XML feed itself and then again for all posts listed under `blog`). Performance wasn't the initial goal when I first launched this project, but now that the dust has settled it seemed appropriate to go back and fix some things. + +`pblog` now only needs to render the blog posts found in the `posts` directory *once*. It still produces semantic XML and keeps the webview versions of the articles looking solid. Overall I'm pretty happy with this *little* improvement - it should pretty noticeable on projects rendering many posts. + +## Far From Perfect + +This project is still very much in it's infancy. So if you notice something odd or broken in your own testing, please don't hesitate to open a patch or simply bring up the issue! + +Thanks for reading, + +-- Brad \ No newline at end of file diff --git a/posts/pblog-intro.md b/posts/pblog-intro.md new file mode 100644 index 0000000..e86272b --- /dev/null +++ b/posts/pblog-intro.md @@ -0,0 +1,96 @@ +--- +title: Introducing pblog +date: Mon, 04 Jul 2022 +--- + +This article is a *living document*. It will always have the most up-to-date information on getting started with `pblog`. + +**Last Updated**: July 27, 2022 + +--- + +Although this project was already [announced](/blog/pblog-launch.html) a couple days ago, I thought it might be best to actually breakdown `pblog` into greater detail. + +Enough chit-chat, let's get into it! + +### Main Goal + +The entire purpose of `pblog` is to be as bare-bones as possible, while still maintaining a pleasant writing workflow. Users write their posts and pages in Markdown - *pblog* handles everything else: + +- Posts and pages generated via Pandoc with minimal CSS +- RSS feed at `feed.xml` +- Generated blog listing at `blog/index.html` +- Browser-styled XML (in supported browsers) + +### Site Structure + +After you've cloned the [official pblog repo on sourcehut](https://git.btxx.org/pblog), the next thing you should do is edit the main `_config.sh` file in the root directory. This will give you a better understanding of how everything is built. + +Once generated, *pblog* structures the final website files as such: + +```shell +_output/ + |__blog/ + |__index.html + |__blog-post-example.html + |__media/ + |__feed.xml + |__index.html + |__rss.xsl + |__style.css +``` + +This structure is completely customizable by simply editing the `_config.sh` file (if you so desire). + +### Headers and Footers + +By default `pblog` will add the header and footer includes to every individual post and page. To edit these, simply open the `_header.html` and `_footer.html` files respectively. + +**Important**: To avoid rendering issues DO NOT remove the included `article` opening and closing tags within those files. Everything else you can edit, remove, etc. + +### Posts and Pages + +Posts and pages are written via Markdown inside the `posts` and `pages` folders respectively. + +Individual posts require the following headers (take note of the date format): + +```yaml +--- +title: Blog Title +date: Mon, 04 Jul 2022 +--- +``` + +while individual pages only require a `title`: + +```yaml +--- +title: Page Title +--- +``` + +This makes for an easier switch over from other SSG platforms like Jekyll or Hugo. + +### The Build Process + +The main variables at the top of the `pblog.sh` file need to edited with your own details before generating your website. Those variables are fairly self-explanatory and simple to edit. + +All you need to do now is run `make` (or `make serve` if you're looking to test locally) and you're done. Your website should now be fully generated inside the include `_output` directory. For quick reference: + +1. *pblog* converts your Markdown posts into two variations of HTML + - One is used specifically for rendering itself inside the RSS feed + - The other is used for linking in a browser +2. Next, *pblog* converts your Markdown pages into HTML +3. All of these generated HTML files are then moved to the `_output` folder + +*pblog* is also smart enough to automatically generate a main blog list directory for you. This `index.html` file is placed inside the `_output/blog` folder on build. You can see an example of the blog list [on this very website](/blog). + +### Uploading to the WWW + +Those with more experience will probably lean towards using a utility like `rsync` to sync the contents of their `_output` folder with their web server. For those with less experience, I recommend using something like [Netlify Drop](https://app.netlify.com/drop) to make things as friction-less as possible. + +### Wrapping Up + +There isn't much else to say. `pblog` is as static or flexible as you chose it to be. If you have any ideas on how to improve things or come across any bugs, please [open a ticket or PR on the official repo](https://git.sr.ht/~bt/pblog). + +Thanks and happy blogging with *pblog*! diff --git a/posts/pblog-launch.md b/posts/pblog-launch.md new file mode 100644 index 0000000..3c9b472 --- /dev/null +++ b/posts/pblog-launch.md @@ -0,0 +1,11 @@ +--- +title: Announcing pblog +date: Thu, 30 Jun 2022 +--- + +It's time to celebrate! The official launch of `pblog` happened today. + +There isn't much else to say. All details and instructions on how to start your own pblog can be found on the [main homepage for this project](https://pblog.btxx.org). + +Thanks for reading! + diff --git a/posts/small-patch.md b/posts/small-patch.md new file mode 100644 index 0000000..d6c1507 --- /dev/null +++ b/posts/small-patch.md @@ -0,0 +1,27 @@ +--- +title: Includes, rsync and Variables - Oh My! +date: Fri, 08 Jul 2022 +--- + +Even though `pblog` was just launched a week ago, it has since been updated with some nice quality-of-life improvements. + +### Default "header" & "footer" Includes + +A new variable was added to the main `pblog.sh` configuration file called `INC_HEAD_FOOT`. By default this is set to `true` and simply pulls in two HTML files: + +- `_header.html`: all content within is placed directly after the opening `body` tag +- `_footer.html`: all content within is placed directly before the closing `body` tag + +These includes are added to every outputted file from inside both the `posts` and `pages` directories on build. + +### Syncing Changes with rsync + +Although it adds another dependency to the project, I believe utilizing `rsync` for the generated files is far better then nuking the directory from orbit each time. This also provides a cleaner experience for users syncing their `_output` directory with their web server of choice. + +### On the Horizon... + +My plan was to also tackle the issue of "auto rebuilds" when running `pblog` locally. This became more of a headache than I initially estimated - so it was dropped from this patch. My hope is to get something up-and-running in the near future, while avoiding the inclusion of yet another major dependency. Anyone more experienced than myself in the ways of "auto rebuilds" is free to open a patch if they so desire! + +Thanks for your interest in these minor updates! + +P.S. Don't forget - if your website runs on `pblog` be sure to reach out and get it featured on the [homepage](/)! diff --git a/rss.xsl b/rss.xsl new file mode 100644 index 0000000..2b54fe5 --- /dev/null +++ b/rss.xsl @@ -0,0 +1,66 @@ + + + + + + + + <xsl:value-of select="/rss/channel/title" /> + + + + + + + + + + + + + +
+

+

+ +

+
+ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/style.css b/style.css new file mode 100644 index 0000000..6c1cca6 --- /dev/null +++ b/style.css @@ -0,0 +1,50 @@ +html { + background:#f9f9f9; +} + +body { + background: #fff; + border: 1px solid lightgrey; + margin: 1em auto; + max-width: 75ch; + padding: 10px; + line-height: 1.4; +} + +p code, li code { + border: 1px solid brown; + border-radius: 2px; + color: brown; + padding: 1px 2px; +} +.sourceCode { + overflow: auto; +} + +img { + height: auto; + max-width: 100%; +} + +pre { + background: #f9f9f9; + border: 1px solid lightgrey; + padding: 5px; +} + +#TOC { + border: 1px solid; + position: relative; +} +#TOC:before { + border-bottom: 1px solid; + content: 'Table of Contents'; + display: block; + font-weight: bold; + padding: 5px; + position: relative; +} + +.date { + color: grey; +} -- cgit v1.2.3-54-g00ecf