Shinobi

SIMPLE GUIDE FOR CREATING YOUR OWN SHINOBI.WEBSITE

bt@btxx.org(Bradley Taunt) — Thu, 21 Apr 2022 12:37:54 EST

Learn how to setup your own Shinobi site without the need for any 
technical background.

I'm going to keep this article as streamlined as possible. This post 
assumes you understand _what_ a shinobi website is and will therefore 
skip reiterating that. Instead we will break things down into basic 
step-by-step instructions.


STEP 1
------

Create a new folder (where you think it is best on your system). This 
will contain all the files for our shinobi website. Name it what ever 
you like.


STEP 2
------

Download the following project:

https://git.sr.ht/~tdarb/shinobi-script


STEP 3
------

Edit the following content in the newly created "script.sh" to align 
with your own settings. (ie: YOUR-DOMAIN would be 
"yourcustomdomain.com") Feel free to use any text editor that works 
best for you.

1. YOUR-DOMAIN
2. YOUR-EMAIL (YOUR-NAME)
3. YOUR-BLOG-TITLE
4. YOUR-BLOG-DESCRIPTION
5. YOUR-COPYRIGHT-INFO

*Important*: You might not have a domain setup currently or plan to use 
the one generated by Netlify Drop below. That's okay! You can always 
come back to this step after the domain is live, change it and re-run 
everything again to update!


STEP 4
------

Next, look for the folder named "posts". This will contain all your 
blog posts going forward. (It also contains a couple dummy posts for 
reference)


STEP 5
------

Write your first blog post! Create a new text file inside the "posts" 
sub-folder (ie: my-awesome-post.txt). Be sure to structure the first 4 
lines the same as below: (Pay attention to the blank space between the 
title and post description!)

> Thu, 21 Apr 2022
> YOUR BLOG POST TITLE
> 
> This is my short and sweet blog post description


STEP 6
------

If you are happy with your article then that means it's time to 
generate your site! Open a terminal app in your system (Windows, Mac, 
Linux - doesn't matter) and navigate to your new website folder by 
typing the following:

cd path/to/your/blog/folder


STEP 7
------

Now run the bash script to generate the "feed.xml" file automatically:

bash script.sh > feed.xml


STEP 8
------

Now to host your new website! For this tutorial we are going to use 
Netlify Drop for simplicity and ease-of-use. Go to 
https://app.netlify.com/drop and then drag-and-drop your website folder 
directly into the website.

You'll get a ".netlify.app" based URL, unless you decide to implement a 
custom domain (which is easy to do following Netlify's instructions).

Now you can share your "subdomain.netlify.app/feed.xml" with the world 
and your readers can subscribe via RSS!


WHAT ABOUT NEW POSTS OR UPDATES?
--------------------------------

By getting a free Netlify account you can continue to re-upload the 
website folder when you make changes or add new articles. Easy, right?

Good luck on your own shinobi websites!


P.S. Feel free to reach out to me if you have any questions via 
shinobi.web@protonmail.com. I'll try to respond as quick as I can. 
Please be patient!

FULL POSTS ARE NOW RENDERED INSIDE RSS READERS

bt@btxx.org(Bradley Taunt) — Fri, 06 May 2022 12:37:54 EST

Your subscribers can now read your full articles without leaving the 
comfort of their RSS readers.

I have finally succeeded after fighting with properly rendering full 
post content directly _inside_ RSS readers. I struggled with this 
implementation far longer than I'd like to admit. Although, that's to 
be expected with my caveman knowledge of RSS feeds and my simple monkey 
brain.

But here we are! We made it.


INSPIRATION
-----------

The thought of rendering all the content within users' RSS readers was 
always something I wanted for the initial launch of Shinobi Website. It 
was taking me a while to understand the layout issues caused by 
articles being pure plain text, so I ended up giving up for version 
"1.0".

Then fellow web-minimalist Matthew Graybosch kindly reached out and 
showed off his own beautifully crafted shinobi website[0]. Browsing 
through his site and articles I quickly realized a few rendering woes 
of my own:

1. Having set the reading length to 72, I was hurting the reading 
experience for mobile users
2. Matthew was doing a lot more cool things on his site (D&D style 
tables, separating specific feeds into their own directories)

Shortly after this exchange I was contacted by another plain-text web 
enthusiast, Koray Er[1].  They were inspired to start building out 
their own Shinobi Website. This is where the question was brought up 
regarding full post rendering:

> i want the entire content in my rss reader - not just one line. the 
best i could do was put $(tail -n +4 $file) in the description. that 
works, but without line breaks. is it possible to fix that in rss.sh? i 
don't want to change the txt - it's so pure.

This was the final straw. I _needed_ to get this working in _some_ 
capacity.


CDATA TO THE RESCUE
-------------------

I played around with converting plain text to HTML and pasting it 
inside the XML at build time. This created more problems than it fixed. 
But finally, after roughly 2 hours of going down multiple rabbit holes 
of failure, I mashed together a few concepts from everyone's trusty 
copy/paste site: stackoverflow.

Take a look at the newly updated shell script here:

> https://shinobi.website/script.sh

The only change I have made is inside the `description` tag within the 
individual `item` elements. Take a look if you're interested.

Wait, what the heck that CDATA junk, you might be asking?

> CDATA is defined as blocks of text that are not parsed by the parser, 
but are otherwise recognized as markup.

After that we use `sed` to swap out any newlines with HTML line break 
elements. Nothing crazy there.

NOTE:
As you may have noticed on the main page of this project, the `rss.sh` 
code snippet has been replaced with a direct link to a new `script.sh`. 
Those wishing to implement this new style of formatting will need to 
make the shell changes manually.


CAVEATS
-------

Please note that if you are planning to render your content this way 
there are minor things to look out for.

1. Pasting code examples is a big no-no. The content will be mangled 
and the reader will try to render example snippets as HTML elements. 
Your best bet is to link directly to example files elsewhere in your 
directory.

^ THIS IS NO LONGER TRUE. See details below.[2]

2. This may not work for every single RSS Reader. I can't test every 
application out there in the wild nor can I double check different 
operating systems. All I know is this renders fine for me on macOS 
using NetNewsWire.


FOOTNOTES
---------
[0]: https://matthewgraybosch.com/
[1]: https://korayer.de/
[2]: This issue has been fixed thanks to Matthew Graybosch's excellent 
patch. See patch notes here: 
https://git.sr.ht/~tdarb/shinobi-script/log?from=7e2f8bd312d648ff1c8d3cf
dc747d2e5634100d7#log-7e2f8bd312d648ff1c8d3cfdc747d2e5634100d7


Thanks for reading my humble blog (maybe directly in your RSS reader 
this time too!),
-- Brad

INTRODUCING SHINOBI.WEBSITE

bt@btxx.org(Bradley Taunt) — Thu, 14 Apr 2022 12:37:54 EST

What is a shinobi website?

I have finally been blessed with enough extra free-time to launch my 
small shinobi.website "system" into the wild! My hope is that others 
take inspiration from it and even start shinobi blogs/sites of their 
own.


SHINOBI.WEBSITE EXPLAINED
-------------------------

Quoting the homepage of https://shinobi.website:

> A shinobi website is a text-based, RSS focused blogging "system"

More details about the naming decision, running the simple bash script 
and properly writing plain text blog posts can be found on the 
homepage. For this specific post I more of less want to focus on the 
initial "launch" of the product and what the future holds for this URL 
as a whole.


WHAT TO EXPECT
--------------

If you're reading this post, you have shown interest in this project. 
First off, I would like to thank you for taking the time subscribing to 
this feed or sneakily finding the direct link URL to this post. You are 
a true web shinobi.

As for articles posted here; they will cover topics about minimalism, 
open source software, writing prompts, HTML/CSS hacks and video game 
reviews. This place is an ever-evolving project, I'm not going to 
restrict myself too much by hard constraints or limited topics.

For my next set of posts, I plan to cover a more step-by-step tutorial 
on setting up your own shinobi website through Netlify (for free!). 
After that I have a couple other concepts to follow-up with:

1. A clean Sublime Text setup for writing plain text posts
2. Easy steps to de-clutter and minimize your digital life
3. Switching over from a static site generator to a shinobi website


EXCITED TO INSPIRE
------------------

I'm excited to see if this project inspires even *one* person to do the 
same. If it gets enough traction, I'll need to post a list or "club" 
somewhere for the shinobi community to show-off their work. It will be 
an interesting endeavour to watch grow and I'm looking forward to 
sharing the experience with you, dear reader!


Thanks for reading my humble blog,
-- Brad

FIRST MAJOR PATCH AND QOL IMPROVEMENTS

bt@btxx.org(Bradley Taunt) — Sun, 15 May 2022 12:37:54 EST

The main shinobi script has received its first external patch!

It's getting just past 10PM on this stormy Sunday night, but I have an 
urge to share this post now instead of waiting for next week. 
Afterwards I'll be going to bed before the start of a new week.

If you've been following along, you might have noticed a pretty solid 
patch has been added to the core shinobi script project:

https://git.sr.ht/~tdarb/shinobi-script

Special shout out to Matthew Graybosch[0] for putting together these 
improvements and working towards a more consistent experience across 
all RSS readers.


THE CHANGES AT A GLANCE
-----------------------

In a nutshell:

- text inside the CDATA tag is now wrapped with  tags
-  tag has inline CSS to specify reasonable wrapping
- tail command to retrieve post text now pipes into sed to escape HTML 
tags.
- added test posts
- added makefile for local testing

Please take a look at the changes directly in the official patch 
notes[1]. Take notice of some of the new folders/files included with 
the default project. You'll also see updated instructions in the README 
to help with testing and local development.


QUALITY OF LIFE
---------------

In addition to the first major patch, I've included basic styling to 
properly render the RSS feed directory in supported browsers. To see it 
in action, simply check out:

https://shinobi.website/feed.xml

The styles are included in the new `rss.css` file of the shinobi 
project. The current layout is taken from Len Falken's main 
directory[2]. Feel free to change this to however you see fit! I've 
kept them consistent with the remainder of the project, but there is 
nothing stopping you from including things like XSLT.

To reflect these changes, I've updated some of the details found in the 
original "SIMPLE GUIDE FOR CREATING YOUR OWN SHINOBI.WEBSITE"[3]


TESTING, TESTING, TESTING
-------------------------

I'm trying my best to test every RSS reader available to me. My main 
machine is running macOS and my phone iOS, thus making me somewhat 
limited in my access to other OS-specific RSS applications. Even still, 
I've added a growing list to the project README documenting readers 
that have been tested, along with their support "grade". Feel free to 
include your own testing in tickets or patches on your own!

That is really all there is to say. Enjoy your week!


LINKS
-----

[0]: https://matthewgraybosch.com
[1]: 
https://git.sr.ht/~tdarb/shinobi-script/log?from=7e2f8bd312d648ff1c8d3cf
dc747d2e5634100d7#log-7e2f8bd312d648ff1c8d3cfdc747d2e5634100d7
[2]: http://len.falken.directory
[3]: https://shinobi.website/posts/create-your-own-shinobi-website.txt


***

Thanks for reading,
-- Brad

CUSTOMIZED RSS FEED WITH XSLT

bt@btxx.org(Bradley Taunt) — Tue, 31 May 2022 12:37:54 EST

I've finally merged in the latest changes from the `patch-2` branch 
into `master`. This patch includes a fairly decent update to the 
shinobi structure as a whole:

- Set all configuration options as variables for easier editing and 
updating
- Customized XML feed to match "plain text" style (in supported 
browsers)
- Option to wrap all posts at a 72 character limit for improved 
readability in the browser (commented out by default)


THE NEW RSS FEED "LOOK"
-----------------------

For demo purposes, simply visit the following link in any supported 
browser to see the XSLT in action:

https://shinobi.website/feed.xml


WRAPPING PLAIN TEXT
-------------------

You now have the ability to have shinobi automatically wrap your plain 
text files at a 72 character limit. Since this is _slightly_ more 
advanced, you will need to perform some minor edits to the `script.sh` 
file itself. Don't worry - I've updated the main README file with 
detailed instructions on how to set this up under the section "ADVANCED 
SETTING: WRAPPING PLAIN TEXT":

https://git.sr.ht/~tdarb/shinobi-script


That's all for now. Enjoy the rest of your week!
- Brad

INTERACTIVE LINKS INSIDE XML FEEDS

bt@btxx.org(Bradley Taunt) — Tue, 14 Jun 2022 12:37:54 EST

Today I pushed out a minor change to include clickable, interactive 
links inside the generated XML feed. This isn't anything groundbreaking 
but greatly improves the user experience for those visiting the RSS 
file directly in their browser. The full changes can be found in the 
official repo for this project.

You can see a live example on this very website:

https://shinobi.website/feed.xml

and also on my own personal website:

https://tdarb.org/feeds/posts.xml

I plan to do a larger, more detailed write-up on how this is 
accomplished on my personal blog within the coming days. Subscribed to 
that feed if that is something you might be interested in.

Thanks for reading,
- Brad

THE SHINOBI SCRIPT IS NOW AVAILABLE ON SOURCEHUT

bt@btxx.org(Bradley Taunt) — Mon, 09 May 2022 12:37:54 EST

The basic shell script that builds shinobi websites is now on sourcehut 
and licensed under MIT.

Like the title of this post says: the shinobi build script is now 
available on sourcehut:

> https://git.sr.ht/~tdarb/shinobi-script

The original downloadable `script.sh` file will now redirect to this 
repo to ensure users are provided the most up-to-date version. The last 
thing I want is conflicting scripts being used out in the wild!


IMPROVEMENTS WELCOME
--------------------

I wanted to have this available to the public from day one but life has 
been busy! Special shout-out to `prx` for suggesting QoL improvements 
to the script[0]. I haven't tried implementing these suggested changes 
yet, if anyone wants to beat me to it...go for it! This is why the 
shinobi script needs to be more in the open. It can improve over time 
with the help of people _much_ smarter than myself!


WHY SOURCEHUT AND NOT GITHUB?
-----------------------------

I like to support competition and help reduce growing monopolies. 
Github is great for what it is but I have enough projects "stuck" on 
that platform. It's nice to diversify your git hosting!


LINKS
-----

[0]: https://si3t.ch/Logiciel-libre/atom-awk.xhtml


***

That's all folks, thanks for reading!
-- Brad