From ce014adb0d139bc09d388129903a8e854fb473ba Mon Sep 17 00:00:00 2001 From: Bradley Taunt Date: Wed, 31 Jan 2024 09:52:56 -0500 Subject: Use proper markdown README --- README | 170 -------------------------------------------------------------- README.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+), 170 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 2f2105f..0000000 --- a/README +++ /dev/null @@ -1,170 +0,0 @@ -barf ----- - -barf is an extremely minimal blog generator. - -The entire build script is less than 100 lines of shell. - -It could *almost* be called "suckless", but probably isn't. - -(barf is a modified/forked version of Karl Bartel's fantastic blog.sh -(https://github.com/karlb/karl.berlin). Be sure to check it out since -my version does things slightly different.) - -You can see a [live demo here](https://barf.btxx.org) - -why 'barf'? ------------ - -> **barf** -> -> blogs are really fun - - -core features -------------- - -- Extremely portable -- Automatic, **valid** RSS generation -- Handles both blog posts and normal pages -- No front matter or templating, just create markdown files - -requirements ------------- - -`barf` was originally built on and for Linux, but has since been -updated to include support for both OpenBSD and MacOS out-of-the-box. - -linux ------ - -- rsync -- smu (see below) -- entr (optonal) -- standard UNIX tools - -openbsd -------- - -Please refer to the main tutorial on setting up barf on OpenBSD: -https://barf.btxx.org/openbsd - -- coreutils -- gcc -- cmake -- rsync -- gsed -- smu (see below) -- entr (optional) - -macOS ------ - -Please refer to the main tutorial on setting up barf on MacOS: -https://barf.btxx.org/macos - -- coreutils -- gnu-sed -- rsync -- smu (see below) -- entr (optional) - -basic setup ------------ - -Clone this repo and navigate inside it. Edit the "header.html" -and "footer.html" files with your own information, navigation, etc. - -Be sure to edit the **RSS meta url** or else your feed won't validate! - -Then, clone and build my patched version of smu: - - -$ git clone https://git.btxx.org/smu -$ cd smu -# OpenBSD users: change sudo to doas -$ sudo make install - - -Then clone this directory and build: - - -$ make build - - -Your blog content will be in the `build` directory. - -Now you can delete the dummy posts/pages and start making your own! - -Media (such as images, videos) are placed in the "public" folder and -carried over to the "build" folder via rsync. You can easily remove -this altogether inside the main `barf` script if you plan to store -media elsewhere (or not use any at all). - -post structure --------------- - -The first line of any markdown file inside your `posts` directory -should start with a h1 heading, then a line break, then the date -in `YYYY-MM-DD` format. - -Like so: - - - # This is the Post Title - - 2023-01-05 - - -Changing this structure or date format will break things or require -you to edit the `barf` script accordingly. - -projects goals --------------- - -- The core focus should be to **reduce** the code of this project, - not increase it. Overall scope needs to remain small. -- Major tweaks/add-ons should be run by individuals via forks/patches, - not put into the barf base - -submitting patches ------------------- - -Please send me patches via git email: barf@patches.btxx.org - -Thanks! - - -FAQs ----- - -## How do I test locally? - -Inside your project directory run: - -```sh -make watch -cd build && python3 -m http.server 3003 -``` - -## Do you plan to add "X"? Can *I* add "X"? - -Most likely not. I'm happy with how things are currently. If you -want to add something - great! The point of this project is to give -others the ability to fork it, tweak it, patch it, and share it as -much as they'd like. The core of barf will remain minimal for this reason. - -Of course, any patches that can help *reduce* the project's footprint -or even speed things up are more than welcome! - -## Can I use other Markdown parsers? - -Of course! Simply edit the main `barf` script and swap out `smu` with -something else. I wouldn't advise doing this if you already have pre-existing -content based-off `smu`, since this could break some of your pages. - -But give smu (https://git.btxx.org/smu) a try - it is very lightweight and fast! - - -MORE FAQs TO COME... - diff --git a/README.md b/README.md new file mode 100644 index 0000000..2f2105f --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +barf +---- + +barf is an extremely minimal blog generator. + +The entire build script is less than 100 lines of shell. + +It could *almost* be called "suckless", but probably isn't. + +(barf is a modified/forked version of Karl Bartel's fantastic blog.sh +(https://github.com/karlb/karl.berlin). Be sure to check it out since +my version does things slightly different.) + +You can see a [live demo here](https://barf.btxx.org) + +why 'barf'? +----------- + +> **barf** +> +> blogs are really fun + + +core features +------------- + +- Extremely portable +- Automatic, **valid** RSS generation +- Handles both blog posts and normal pages +- No front matter or templating, just create markdown files + +requirements +------------ + +`barf` was originally built on and for Linux, but has since been +updated to include support for both OpenBSD and MacOS out-of-the-box. + +linux +----- + +- rsync +- smu (see below) +- entr (optonal) +- standard UNIX tools + +openbsd +------- + +Please refer to the main tutorial on setting up barf on OpenBSD: +https://barf.btxx.org/openbsd + +- coreutils +- gcc +- cmake +- rsync +- gsed +- smu (see below) +- entr (optional) + +macOS +----- + +Please refer to the main tutorial on setting up barf on MacOS: +https://barf.btxx.org/macos + +- coreutils +- gnu-sed +- rsync +- smu (see below) +- entr (optional) + +basic setup +----------- + +Clone this repo and navigate inside it. Edit the "header.html" +and "footer.html" files with your own information, navigation, etc. + +Be sure to edit the **RSS meta url** or else your feed won't validate! + +Then, clone and build my patched version of smu: + + +$ git clone https://git.btxx.org/smu +$ cd smu +# OpenBSD users: change sudo to doas +$ sudo make install + + +Then clone this directory and build: + + +$ make build + + +Your blog content will be in the `build` directory. + +Now you can delete the dummy posts/pages and start making your own! + +Media (such as images, videos) are placed in the "public" folder and +carried over to the "build" folder via rsync. You can easily remove +this altogether inside the main `barf` script if you plan to store +media elsewhere (or not use any at all). + +post structure +-------------- + +The first line of any markdown file inside your `posts` directory +should start with a h1 heading, then a line break, then the date +in `YYYY-MM-DD` format. + +Like so: + + + # This is the Post Title + + 2023-01-05 + + +Changing this structure or date format will break things or require +you to edit the `barf` script accordingly. + +projects goals +-------------- + +- The core focus should be to **reduce** the code of this project, + not increase it. Overall scope needs to remain small. +- Major tweaks/add-ons should be run by individuals via forks/patches, + not put into the barf base + +submitting patches +------------------ + +Please send me patches via git email: barf@patches.btxx.org + +Thanks! + + +FAQs +---- + +## How do I test locally? + +Inside your project directory run: + +```sh +make watch +cd build && python3 -m http.server 3003 +``` + +## Do you plan to add "X"? Can *I* add "X"? + +Most likely not. I'm happy with how things are currently. If you +want to add something - great! The point of this project is to give +others the ability to fork it, tweak it, patch it, and share it as +much as they'd like. The core of barf will remain minimal for this reason. + +Of course, any patches that can help *reduce* the project's footprint +or even speed things up are more than welcome! + +## Can I use other Markdown parsers? + +Of course! Simply edit the main `barf` script and swap out `smu` with +something else. I wouldn't advise doing this if you already have pre-existing +content based-off `smu`, since this could break some of your pages. + +But give smu (https://git.btxx.org/smu) a try - it is very lightweight and fast! + + +MORE FAQs TO COME... + -- cgit v1.2.3-54-g00ecf