forked from team/bashblog
436 lines
9.5 KiB
Groff
436 lines
9.5 KiB
Groff
.\" Automatically generated from an mdoc input file. Do not edit.
|
|
.\" Use mandoc -T man ./bb.1.mdoc > bb.1.man to conver to the old
|
|
.\" (but still actively encouraged) Linux "an" format.
|
|
.TH "BB" "1" "November 7, 2022" "Linux 3.10.0-1160.76.1.el7.x86_64" "General Commands Manual"
|
|
.nh
|
|
.if n .ad l
|
|
.SH "NAME"
|
|
\fBbb\fR
|
|
\- A single bash script to create blogs
|
|
.SH "SYNOPSYS"
|
|
\fBbb\fR
|
|
\fBpost\fR
|
|
[\fB\-html\fR]
|
|
[\fIfilename\fR]
|
|
.PP
|
|
\fBbb\fR
|
|
\fBedit\fR
|
|
[\fB\-n\fR
|
|
|
|
|
\fB\-f\fR]
|
|
\fIfilename\fR
|
|
.PP
|
|
\fBbb\fR
|
|
\fBdelete\fR
|
|
\fIfilename\fR
|
|
.PP
|
|
\fBbb\fR
|
|
\fBrebuild|reset|list\fR
|
|
.PP
|
|
\fBbb\fR
|
|
\fBtags\fR
|
|
[\fB\-n\fR]
|
|
.SH "DESCRIPTION"
|
|
When invoked without arguments or with invalid arguments,
|
|
\fBbb\fR
|
|
will print usage. Before you go any further, you may want to check the CONFIGURATION section.
|
|
.PP
|
|
\fBbb\fR
|
|
\fBpost\fR
|
|
will open your
|
|
\fR$EDITOR\fR
|
|
to author a new post in markdown. if available, else in html directly. Use
|
|
\fBbb\fR
|
|
\fBpost\fR
|
|
\fB\-html\fR
|
|
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
|
|
(\(lap\(ra),
|
|
edit
|
|
(\(laE\(ra)
|
|
or keep this for later as a draft
|
|
(\(lad\(ra).
|
|
Posts will be served at
|
|
\fBhttps://tilde.club/~you/blog/\fR
|
|
Specifying a
|
|
\fIfilename\fR
|
|
will pre-load the editor with the contents of that file.
|
|
\fIfilename\fR
|
|
is relative to
|
|
\fI~/public_html/blog/.\fR
|
|
.PP
|
|
\fBbb\fR
|
|
\fBedit\fR
|
|
\fIfilename\fR
|
|
allows you to edit an already published .html or .md file.
|
|
\fIfilename\fR
|
|
is relative to
|
|
\fR~/public_html/blog\fR
|
|
and can be either the .md or .html.
|
|
\fBNever\fR
|
|
manually edit a published .html file, always use this function as it
|
|
keeps internal data and rebuilds the blog.
|
|
Use
|
|
\fB\-n\fR
|
|
to give the file a new name, if the title is changed.
|
|
Use
|
|
\fB\-f\fR
|
|
to edit the full html.
|
|
.PP
|
|
\fBbb\fR
|
|
\fBdelete\fR
|
|
\fIfilename\fR
|
|
will delete a post and rebuild the blog.
|
|
.PP
|
|
\fBbb\fR
|
|
\fBrebuild\fR
|
|
regenerates all pages and posts, preserving the content of the entries.
|
|
.PP
|
|
\fBbb\fR
|
|
\fBreset\fR
|
|
deletes everything. Use with caution and
|
|
\fIbackup everything\fR
|
|
first.
|
|
.PP
|
|
\fBbb\fR
|
|
\fBlist\fR
|
|
lists all posts.
|
|
.PP
|
|
\fBbb\fR
|
|
\fBtags\fR
|
|
lists all tags in alphabetical order.
|
|
\fB\-n\fR
|
|
sorts by number of posts under each tag.
|
|
.SH "ENVIRONMENT"
|
|
The following environment variables are used by
|
|
\fBbb\fR
|
|
:
|
|
.TP 9n
|
|
\fREDITOR\fR
|
|
Tell
|
|
\fBbb\fR
|
|
which editor you want to use to edit your posts.
|
|
.SH "FILES"
|
|
.TP 20n
|
|
\fI~/public_html/blog\fR
|
|
The default path for your production blog folder. Make sure to create this,
|
|
otherwise you will see strange behaviour.
|
|
\fIAll paths are relative to this directory.\fR
|
|
.TP 20n
|
|
\fI.config\fR
|
|
Configuration file overriding the global defaults.
|
|
.TP 20n
|
|
\fIdrafts/\fR
|
|
Folder where you drafts are saved if you choose the
|
|
\(oqd\(cq
|
|
option after exiting your
|
|
\fREDITOR\fR.
|
|
.TP 20n
|
|
\fI.backup.tar.gz\fR
|
|
Backup from before you did something silly.
|
|
.TP 20n
|
|
\fI.yesterday.tar.gz\fR
|
|
A backup from yesterday in case
|
|
\fI.backup.tar.gz\fR
|
|
already includes the silly mistake.
|
|
.SH "CONFIGURATION"
|
|
Global defaults are kept within the
|
|
\fBbb\fR
|
|
sh script itself, in the
|
|
\fBglobal_variables\fR()
|
|
function.
|
|
.PP
|
|
You can create
|
|
\fI~/public_html/blog/.config\fR
|
|
which allows you to set
|
|
\fBbash\fR
|
|
variables which override the global defaults.
|
|
\fINote,\fR
|
|
this is a bash script, so the format is
|
|
.RS 6n
|
|
var="value"
|
|
.RE
|
|
Please do not try to get fancy.
|
|
.SS "General Blog Settings"
|
|
.TP 24n
|
|
global_title
|
|
Blog title
|
|
.TP 24n
|
|
global_description
|
|
The typical subtitle for each blog.
|
|
.TP 24n
|
|
global_url
|
|
The public base URL for this blog.
|
|
.TP 24n
|
|
global_author
|
|
Your name
|
|
.TP 24n
|
|
global_author_url
|
|
You can use your tildehome, Twitter, Facebook, etc. as your
|
|
\(oqglobal_author_url\(cq
|
|
.TP 24n
|
|
global_email
|
|
Your email address.
|
|
.TP 24n
|
|
global_license
|
|
CC by-nc-nd is a good starting point, but you can pick a different license. You can change this to
|
|
\(oq©\(cq
|
|
for Copyright.
|
|
.TP 24n
|
|
global_feedburner
|
|
Set to empty
|
|
(\(oq\(cq)
|
|
if you don't use feedburner, otherwise point it to your URL.
|
|
.TP 24n
|
|
global_twitter_username
|
|
.br
|
|
Set this to your username if you want to use Twitter for comments.
|
|
.TP 24n
|
|
global_twitter_cookieless
|
|
Set this to
|
|
\(oqfalse\(cq
|
|
for a Twitter button with a share count. The cookieless version is just a link. This is to comply to EU GDPR regulations.
|
|
.TP 24n
|
|
global_twitter_search
|
|
Default search page, where tweets more than a week old are hidden.
|
|
.SS "Blog Generated Files Settings"
|
|
.TP 24n
|
|
index_file
|
|
The index page of the blog. Probably a good idea to stick with
|
|
\(oqindex.html\(cq
|
|
.TP 24n
|
|
number_of_index_articles
|
|
How many posts to show on the index page.
|
|
.TP 24n
|
|
archive_index
|
|
Page name of your
|
|
\(lqall posts\(rq
|
|
page.
|
|
.TP 24n
|
|
tags_index
|
|
Page name of your
|
|
\(lqall tags\(rq
|
|
page.
|
|
.TP 24n
|
|
gophermap
|
|
Ignore gophermap?
|
|
.TP 24n
|
|
non_blogpost_files
|
|
A bash array of files that
|
|
\fBbb\fR
|
|
will ignore. Useful for static resources. E.g.
|
|
.RS 30n
|
|
.RE
|
|
.RS 24n
|
|
non_blogpost_files=("news.html" "test.html")
|
|
.RE
|
|
.TP 24n
|
|
blog_feed
|
|
RSS feed file name.
|
|
.TP 24n
|
|
number_of_feed_articles
|
|
.br
|
|
How many posts to put in the RSS feed.
|
|
.TP 24n
|
|
cut_do
|
|
\(lqcut\(rq
|
|
blog entry when putting it to index page. Leave blank for full
|
|
articles in front page, i.e. include only up to first
|
|
\(oq<hr>\(cq
|
|
or
|
|
\(oq----\(cq
|
|
in markdown.
|
|
.TP 24n
|
|
cut_tags
|
|
When cutting, cut also tags? If
|
|
\(oqno\(cq
|
|
, tags will appear in index page for cut articles. If
|
|
\(oqyes\(cq,
|
|
they won't.
|
|
.TP 24n
|
|
cut_line
|
|
regex(7)
|
|
matching the HTML line where to do the cut.
|
|
\fINote\fR
|
|
that the slash is regexp separator so you need to prepend it with backslash
|
|
(\(oq\e\(cq).
|
|
.TP 24n
|
|
save_markdown
|
|
If
|
|
\(oqyes\(cq,
|
|
save markdown file when posting with
|
|
\(oqbb post\(cq
|
|
(and markdown is available).
|
|
.TP 24n
|
|
prefix_tags
|
|
Prefix for tags/categories files. Please make sure no other html file starts with this prefix.
|
|
.TP 24n
|
|
header_file
|
|
.TP 24n
|
|
footer_file
|
|
Personalized header and footer (only if you know what you're doing).
|
|
\fIDO NOT\fR
|
|
name them
|
|
\(oq.header.html\(cq,\(oq.footer.html\(cq
|
|
or they will be overwritten. Leave blank
|
|
("")
|
|
to generate them, which is recommended.
|
|
.TP 24n
|
|
body_begin_file
|
|
Extra content to add just before we open the
|
|
\(oq<body>\(cq
|
|
tag and before the actual blog content.
|
|
.TP 24n
|
|
body_end_file
|
|
Extra content to add just before we close
|
|
\(oq<body>\(cq
|
|
tag (just before
|
|
\(oq</body>\(cq).
|
|
.TP 24n
|
|
css_include
|
|
CSS files to include on every page, e.g.
|
|
.RS 30n
|
|
css_include=('main.css' 'blog.css')
|
|
.RE
|
|
.RS 24n
|
|
Leave blank ("") to use the generated ones.
|
|
.RE
|
|
.TP 24n
|
|
html_exclude
|
|
HTML files to exclude from index, e.g.
|
|
.RS 30n
|
|
html_exclude=('imprint.html' 'aboutme.html')
|
|
.RE
|
|
.SS "Localization and Internationalization"
|
|
.TP 24n
|
|
template_comments
|
|
\(lqComments?\(rq
|
|
(used in twitter link after every post).
|
|
.TP 24n
|
|
template_read_more
|
|
\(lqRead more...\(rq
|
|
(link under cut article on index page).
|
|
.TP 24n
|
|
template_archive
|
|
\(lqView more posts\(rq
|
|
(used on bottom of index page as link to archive).
|
|
.TP 24n
|
|
template_archive_title
|
|
\(lqAll posts\(rq
|
|
(title of archive page).
|
|
.TP 24n
|
|
template_tags_title
|
|
\(lqAll tags\(rq
|
|
.TP 24n
|
|
template_tags_posts
|
|
\(lqposts\(rq
|
|
(on
|
|
\(lqAll tags\(rq
|
|
page, text at the end of each tag line, like
|
|
\(lq2.Music-15posts\(rq)
|
|
.TP 24n
|
|
template_tags_posts_2_4
|
|
.br
|
|
Some slavic languages use a different plural form for 2-4 items.
|
|
.TP 24n
|
|
template_tags_posts_singular
|
|
Word to use for one post.
|
|
.TP 24n
|
|
template_tag_title
|
|
\(lqPosts tagged\(rq
|
|
(text on a title of a page with index of one tag, like
|
|
\(lqMy Blog - Posts tagged \(oqMusic\(cq\(rq)
|
|
.TP 24n
|
|
template_tags_line_header
|
|
\(lqTags:\(rq
|
|
(beginning of line in HTML file with list of all tags for this article)
|
|
.TP 24n
|
|
template_archive_index_page
|
|
\(lqBack to the index page\(rq
|
|
(used on archive page, it is link to blog index)
|
|
.TP 24n
|
|
template_subscribe
|
|
\(lqSubscribe\(rq
|
|
(used on bottom of index page, it is link to RSS feed)
|
|
.TP 24n
|
|
template_subscribe_browser_button
|
|
\(lqSubscribe to this page...\(rq
|
|
(used as text for browser feed button that is embedded to html)
|
|
.TP 24n
|
|
template_twitter_button
|
|
.br
|
|
\(lqTweet\(rq
|
|
(used as twitter text button for posting to twitter)
|
|
.TP 24n
|
|
template_twitter_comment
|
|
Default comment used to prepopulate the form.
|
|
.TP 24n
|
|
date_format
|
|
strftime(3)
|
|
format to use for dates.
|
|
.TP 24n
|
|
date_locale
|
|
locale(1)
|
|
to use for dates.
|
|
.TP 24n
|
|
date_inpost
|
|
\(oqbashblog_timestamp\(cq
|
|
.TP 24n
|
|
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.
|
|
.TP 24n
|
|
preview_url
|
|
URL where you can view the post while it's being edited. By default, it is
|
|
\(oqglobal_url\(cq\&.
|
|
You can change it to the path on your computer, if you write posts locally, before copying them to the server.
|
|
.SH "EXAMPLES"
|
|
Post a markdown file:
|
|
.RS 6n
|
|
bb post ~/my_new_post.md
|
|
.RE
|
|
then hit
|
|
\(lap\(ra\&.
|
|
.PP
|
|
Continue editing a draft:
|
|
.RS 6n
|
|
bb post drafts/the-title-I-was-thinking-of.md
|
|
.RE
|
|
.SH "SEE ALSO"
|
|
bash(1),
|
|
for a reference on variable assignments.
|
|
.SH "AUTHORS"
|
|
cfenollosa \(la\fIhttps://github.com/cfenollosa\fR\(ra
|
|
.PP
|
|
man page by Vlad Me\[u0219]co \(la\fIalzwded@tilde.club\fR\(ra
|
|
.SH "CAVEATS"
|
|
The tilde.club version imposes that the
|
|
\fIblog\fR
|
|
root directory is
|
|
\fI~/public_html/blog\fR,
|
|
and it will
|
|
cd(1)
|
|
to that directory before doing anything else. This makes all
|
|
\fIpaths\fR
|
|
be relative to that directory.
|
|
.PP
|
|
As a side effect, if the
|
|
\fI~/public_html/blog/\fR
|
|
directory does not exist,
|
|
\fBbb\fR
|
|
will get confused and dump files where you don't expect them. Make sure
|
|
you create that path before running
|
|
\fBbb\fR:
|
|
.RS 6n
|
|
mkdir -p ~/public_html/blog/
|
|
.RE
|
|
.PP
|
|
Post file names might get de-unicoded, so if
|
|
\fBbb\fR
|
|
complains it couldn't find your file, use
|
|
find(1)
|
|
or
|
|
grep(1)
|
|
in
|
|
\fI~/public_html/blog/\fR
|
|
to find them.
|