bashblog/bb.1.mdoc

.\" Use mandoc -T man ./bb.1.mdoc > bb.1.man to conver to the old
.\" (but still actively encouraged) Linux "an" format.
.Dd $Mdocdate$
.Dt BB 1
.Os
.Sh NAME
.Nm bb
.Nd A single bash script to create blogs
.Sh SYNOPSYS
.Nm
.Cm post
.Op Fl html
.Op Pa filename
.Pp
.Nm
.Cm edit
.Oo Fl n
|
.Fl f
.Oc
.Pa filename
.Pp
.Nm
.Cm delete
.Pa filename
.Pp
.Nm
.Cm rebuild|reset|list
.Pp
.Nm
.Cm tags
.Op Fl n
.Sh DESCRIPTION
When invoked without arguments or with invalid arguments,
.Nm
will print usage. Before you go any further, you may want to check the CONFIGURATION section.
.Pp
.Nm
.Cm post
will open your
.Ev $EDITOR
to author a new post in markdown. if available, else in html directly. Use
.Nm
.Cm post
.Fl html
to start a new post using HTML even when markdown is available. After you
save and exit your editor, you will be asked if you want to post
.Sm off
(
.Aq p
),
.Sm on
edit
.Sm off
(
.Aq E
)
.Sm on
or keep this for later as a draft
.Sm off
(
.Aq d
).
.Sm on
Posts will be served at
.Lk https://tilde.club/~you/blog/
\.
Specifying a
.Pa filename
will pre-load the editor with the contents of that file.
.Pa filename
is relative to
.Pa ~/public_html/blog/.
.Pp
.Nm
.Cm edit
.Pa filename
allows you to edit an already published .html or .md file.
.Pa filename
is relative to 
.Ev ~/public_html/blog
and can be either the .md or .html.
.Sy Never
manually edit a published .html file, always use this function as it
keeps internal data and rebuilds the blog.
Use
.Fl n
to give the file a new name, if the title is changed.
Use
.Fl f
to edit the full html.
.Pp
.Nm
.Cm delete
.Pa filename
will delete a post and rebuild the blog.
.Pp
.Nm
.Cm rebuild
regenerates all pages and posts, preserving the content of the entries.
.Pp
.Nm
.Cm reset
deletes everything. Use with caution and
.Em backup everything
first.
.Pp
.Nm
.Cm list
lists all posts.
.Pp
.Nm
.Cm tags
lists all tags in alphabetical order.
.Fl n
sorts by number of posts under each tag.
.Sh ENVIRONMENT
The following environment variables are used by
.Nm
:
.Bl -tag -width EDITORX
.It Ev EDITOR
Tell
.Nm
which editor you want to use to edit your posts.
.Sh FILES
.Bl -tag -width x/public_html/blog
.It Pa ~/public_html/blog
The default path for your production blog folder. Make sure to create this,
otherwise you will see strange behaviour.
.Em All paths are relative to this directory.
.It Pa .config
Configuration file overriding the global defaults.
.Pp
.It Pa drafts/
Folder where you drafts are saved if you choose the
.Sq d
option after exiting your
.Ev EDITOR .
.It Pa .backup.tar.gz
Backup from before you did something silly.
.It Pa .yesterday.tar.gz
A backup from yesterday in case
.Pa .backup.tar.gz
already includes the silly mistake.
.El
.Sh CONFIGURATION
Global defaults are kept within the
.Nm
sh script itself, in the
.Fn global_variables
function.
.Pp
You can create
.Pa ~/public_html/blog/.config
which allows you to set 
.Sy bash
variables which override the global defaults.
.Em Note,
this is a bash script, so the format is
.Dl var="value"
Please do not try to get fancy.
.Pp
.Ss General Blog Settings
.Bl -tag -width xxxxxxxxxxxxxxxxxxxxxx
.It global_title
Blog title
.It global_description
The typical subtitle for each blog.
.It global_url
The public base URL for this blog.
.It global_author
Your name
.It global_author_url
You can use your tildehome, Twitter, Facebook, etc. as your
.Sq global_author_url
.It global_email
Your email address.
.It global_license
CC by-nc-nd is a good starting point, but you can pick a different license. You can change this to
.Ql ©
for Copyright.
.It global_feedburner
Set to empty
.Sm off
(
.Ql ""
)
.Sm on
if you don't use feedburner, otherwise point it to your URL.
.It global_twitter_username
Set this to your username if you want to use Twitter for comments.
.It global_twitter_cookieless
Set this to
.Ql false
for a Twitter button with a share count. The cookieless version is just a link. This is to comply to EU GDPR regulations.
.It global_twitter_search
Default search page, where tweets more than a week old are hidden.
.El
.Pp
.Ss Blog Generated Files Settings
.Bl -tag -width xxxxxxxxxxxxxxxxxxxxxx
.It index_file
The index page of the blog. Probably a good idea to stick with
.Ql index.html
.It number_of_index_articles
How many posts to show on the index page.
.It archive_index
Page name of your 
.Dq all posts
page.
.It tags_index
Page name of your
.Dq all tags
page.
.It gophermap
Ignore gophermap?
.It non_blogpost_files
A bash array of files that 
.Nm
will ignore. Useful for static resources. E.g.
.Dl
non_blogpost_files=("news.html" "test.html")
.It blog_feed
RSS feed file name.
.It number_of_feed_articles
How many posts to put in the RSS feed.
.It cut_do
.Dq cut
blog entry when putting it to index page. Leave blank for full
articles in front page, i.e. include only up to first 
.Ql <hr>
or 
.Ql ----
in markdown.
.It cut_tags
When cutting, cut also tags? If 
.Ql no
, tags will appear in index page for cut articles. If 
.Sm off
.Ql yes
,
.Sm on
they won't.
.It cut_line
.Xr regex 7
matching the HTML line where to do the cut.
.Em Note
that the slash is regexp separator so you need to prepend it with backslash
.Sm off
(
.Ql \e
).
.Sm on
.It save_markdown
If 
.Sm off
.Ql yes
,
.Sm on
save markdown file when posting with
.Ql bb post
(and markdown is available).
.It prefix_tags
Prefix for tags/categories files. Please make sure no other html file starts with this prefix.
.It header_file
.It footer_file
Personalized header and footer (only if you know what you're doing).
.Em DO NOT
name them
.Sm off
.Ql .header.html
,
.Ql .footer.html
.Sm on
or they will be overwritten. Leave blank
("")
to generate them, which is recommended.
.It body_begin_file
Extra content to add just before we open the
.Ql <body>
tag and before the actual blog content.
.It body_end_file
Extra content to add just before we close
.Ql <body>
tag (just before
.Sm off
.Ql </body>
).
.Sm on
.It css_include
CSS files to include on every page, e.g.
.Dl css_include=('main.css' 'blog.css')
Leave blank ("") to use the generated ones.
.It html_exclude
HTML files to exclude from index, e.g.
.Dl html_exclude=('imprint.html' 'aboutme.html')
.El
.Pp
.Ss Localization and Internationalization
.Bl -tag -width xxxxxxxxxxxxxxxxxxxxxx
.It template_comments
.Dq Comments?
(used in twitter link after every post).
.It template_read_more
.Dq Read more...
(link under cut article on index page).
.It template_archive
.Dq View more posts
(used on bottom of index page as link to archive).
.It template_archive_title
.Dq All posts
(title of archive page).
.It template_tags_title
.Dq All tags
.It template_tags_posts
.Dq posts
(on
.Dq All tags
page, text at the end of each tag line, like
.Sm off
.Dq 2. Music - 15 posts
)
.Sm on
.It template_tags_posts_2_4
Some slavic languages use a different plural form for 2-4 items.
.It template_tags_posts_singular
Word to use for one post.
.It template_tag_title
.Dq Posts tagged
(text on a title of a page with index of one tag, like
.Sm off
.Do "My Blog - Posts tagged "
.Sq Music
.Dc
)
.Sm on
.It template_tags_line_header
.Dq Tags:
(beginning of line in HTML file with list of all tags for this article)
.It template_archive_index_page
.Dq Back to the index page
(used on archive page, it is link to blog index)
.It template_subscribe
.Dq Subscribe
(used on bottom of index page, it is link to RSS feed)
.It template_subscribe_browser_button
.Dq Subscribe to this page...
(used as text for browser feed button that is embedded to html)
.It template_twitter_button
.Dq Tweet
(used as twitter text button for posting to twitter)
.It template_twitter_comment
Default comment used to prepopulate the form.
.It date_format
.Xr strftime 3
format to use for dates.
.It date_locale
.Xr locale 1
to use for dates.
.It date_inpost
.Ql bashblog_timestamp
.It convert_filename
Perform the post title -> filename conversion. Experts only. You may need to tune the locales too. Set to empty ("") for no conversion, which is not recommended. The default filter respects backwards compatibility.
.It preview_url
URL where you can view the post while it's being edited. By default, it is
.Sm off
.Ql global_url
\&.
.Sm on
You can change it to the path on your computer, if you write posts locally, before copying them to the server.
.El
.Sh EXAMPLES
Post a markdown file:
.Dl bb post ~/my_new_post.md
then hit
.Sm off
.Aq p
\&.
.Sm on
.Pp
Continue editing a draft:
.Dl bb post drafts/the-title-I-was-thinking-of.md
.Sh SEE ALSO
.Sm off
.Xr bash 1
,
.Sm on
for a reference on variable assignments.
.Sh AUTHORS
.An cfenollosa Aq Pa https://github.com/cfenollosa
.Pp
.An man page by Vlad Meșco Aq Pa alzwded@tilde.club
.Sh CAVEATS
The tilde.club version imposes that the
.Pa blog
root directory is
.Sm off
.Pa ~/public_html/blog
,
.Sm on
and it will
.Xr cd 1
to that directory before doing anything else. This makes all
.Pa paths
be relative to that directory.
.Pp
As a side effect, if the
.Pa ~/public_html/blog/
directory does not exist,
.Nm
will get confused and dump files where you don't expect them. Make sure
you create that path before running
.Sm off
.Nm
:
.Sm on
.Dl mkdir -p ~/public_html/blog/
.Pp
Post file names might get de-unicoded, so if
.Nm
complains it couldn't find your file, use
.Xr find 1
or
.Xr grep 1
in
.Pa ~/public_html/blog/
to find them.
.\" .Sh BUGS