bearblogr
Installation and Usage Guide
Neo
Tuesday, October 20, 2020
Contents
Overview
Downloads and Installation
Prerequisites
- Git Command Line Tools (optional)
- AWS Command Line Tools (optional)
- Password-less (shared key) Authentication
Configuration Code Blocks
- Each Bear note contains it’s own configuration
bearblogrCode Block ExamplefrontmatterCode Block Example
Bear Note Examples
Known Issues and Caveats
Keyboard Shortcuts
Terms and Conditions
Overview
bearblogr is a tool for macOS that converts the popular Bear app into a content management system (CMS) for your static blog.
It allows you to publish and update content from Bear to a Gatsby, Jekyll, Hugo or other statically generated site in a few simple clicks.
If you want to read more about static sites and using Bear for blogging, check out this article.
The following guide will explain how to install, setup, and use bearblogr for first time users.
Basic workflow
Setting up a Bear note for use with bearblogr is simple:
- Write a blog post as you normally would
- Add in your blog specific configuration using the special
bearblograndfrontmattercode blocks to your note
When you’re ready to publish your Bear note:
- Copy the identifier for your note within the Bear app
_ Right click on the Bear note and select (“Copy Note’s Identifier”)
_ Or use the shortcut:
[ SHIFT ] + [ ALT/OPTION ] + [ ⌘ ] + I - Switch to the bearblogr app and click the
(M)arkdownbutton to generate a markdown file. Markdown files are stored in~/bearblogr/ - Then click the
(G)itbutton. It will automatically clone/pull your Git repo, create a commit, and push the changes back to your remote. - Or, if you have a development server running and would like to preview your content before pushing to Git, you can use the
[ SHIFT ] + Cshortcut to copy the latest revision to your local repo and view your rendered version immediately.
That’s it!
Downloads and Installation
Latest free releases for download
Please note that bearblogr is currently in beta and has been tested on macOS Catalina v10.15.6 only.
Download links:
- Oct 19, 2020 - bearblogr-0.3.0.dmg (BETA)
Latest Pro releases for download
Download links:
Once the .dmg package is downloaded, installation is the same as any other macOS app:
- Mount the package in Finder by double-clicking on it
- Drag the bearblogr app to your Applications folder
- Unmount/eject the package from Finder
Prerequisites
The following prerequisites are necessary if you are planning on publishing content to Git or S3. To make full use of all features, most users should go ahead and install the prerequisites now.
We won’t be going over the step by step details for each service here. Instead, we have included links to resources for detailed guides and explanations on setting them up.
Git Command Line Tools (optional)
In order to commit and push to Git repositories, you will need to have git command line tools installed on your system.
- Please see the instructions for installing Git CLI tools for macOS here.
- Installing Git for a Mac - YouTube
AWS Command Line Tools (optional)
In order to push to Git, you will need to have aws command line tools installed on your system.
- Please see the instructions for installing the AWS CLI tools here.
- Getting Started with AWS S3 CLI - YouTube
Password-less (shared key) Authentication (required)
bearblogr requires password-less authentication if you are planning on using Git or S3. This is both a security requirement as well as a convenience that makes the publishing workflow much smoother.
If you haven’t done this already, here are a few guides that we have found helpful.
For Git:
- neoevolutions | How To Set up SSH Keys
- Connecting to GitHub with SSH - GitHub Docs
- GitLab and SSH keys | GitLab
- Linux/Mac Tutorial: SSH Key-Based Authentication - How to SSH Without a Password - YouTube
For AWS:
- Configuration basics - AWS Command Line Interface
- How to get up and running with AWS CLI on macOS - DEV
- Writing IAM Policies: How to Grant Access to an Amazon S3 Bucket | AWS Security Blog
- Hosting a static website on Amazon S3 - Amazon Simple Storage Service
- Getting Started with AWS S3 CLI - YouTube
We highly recommend testing your Git and AWS configurations by hand first to ensure that they are configured properly before using bearblogr.
Configuration Code Blocks
During processing, bearblogr makes use of special configuration code blocks embedded within each Bear note. They determine how to process and upload your note’s content when you’re ready to publish them to Git or S3.
A few notes about code blocks
- The following code blocks are specific to bearblogr and have no meaning outside of the app. (eg. the
bearblograndfrontmattertags mean nothing to syntax highlighters) - Code blocks are case and whitespace sensitive. If you run into errors or are having issues, please ensure they are formatted correctly first.
- **Code blocks are structured in YAML’s **
key: valueformat. - Keys end with a
:and values are processed directly after the space. - Values, are not required to be enclosed in double
”or single'quotes even if they have spaces.
Each Bear note contains it’s own configuration
bearblogr code blocks are parsed individually for each Bear note. This means that you have the flexibility to write and push content to multiple blogs with a single Bear account.
Currently, bearblogr supports 2 specific types of code blocks:
bearblogr- Configuration for markdown processing, Git, and AWS S3frontmatter- Contains frontmatter for blog post
bearblogr Code Block Example
```bearblogr
md:
fileName: 2020-10-31-Super-Spooky-Halloween-Rocket-Launch
git:
repo: 'git@github.com:elonmusk/spacex-gatsby-blog.git'
repoName: 'spacex-gastby-blog'
repoPath: '/Users/elon/GIT-REPOS'
repoBranch: 'master'
blogPath: 'blog/'
commitMsg: 'Damn, I love bearblogr. Happy Halloween!'
s3:
path: 's3://neoevolutions/blog/posts/'
```md Section (required)
Configuration relevant to markdown output.
fileName- Output filename for your processed markdown file Typically this follows the format/standard for your blog (eg. yyyy-mm-dd-some-URL-friendly-title-with-no-special-characters). Do not include a filename extension (eg*.md,*.MD).
git Section (optional)
Required if you are pushing to Git from bearblogr.
repo- URI for your Git remote repositoryrepoName- Name of your Git repo (without .git)repoPath- Local path where your repo will be storedrepoBranch- Branch in your repo where bearblogr commits toblogPath- Path inside your repo where you store your blog posts (relative to your repo’s root)commitMsg- Custom commit message. Can be changed for each commit to Git. (PRO VERSION ONLY)
s3 Section (optional)
Required if you are pushing to an AWS S3 bucket from bearblogr.
path- URI to your S3 bucket path where markdown files will be stored
frontmatter Code Block Example
```frontmatter
---
title: Super Spooky Halloween Rocket Launch
subtitle: Not for the faint of heart...
path: /blog/2020-10-31-super-spooky-halloween-rocket-launch
date: 2020-10-31T14:18:12.246Z
author: Elon Musk
image: https://spacex.com/logo.png
layout: blog
tags:
- launch
-
- tools
more: custom frontmatter can be added as desired...
---
```Since frontmatter is custom to each blog and application, the code contained within the frontmatter code block will be parsed and added at the head of each exported markdown file without any additional modifications.
Bear Note Examples
[TBD]
Known Issues and Caveats
Known issues with the beta
- The current version of bearblogr requires that
bearblograndfrontmattercode blocks must appear at the top of the note, after the first line. - The
bearblogrcode block should come first, then thefrontmattercode block should come immediately after it. - When pushing to Git or S3, it may appear that the screen has frozen. This is normal. Depending on the size of your commit/upload, this should only take a few seconds to complete.
Keyboard Shortcuts
If you’re a fan of using the keyboard to navigate and control your computer, we’ve added a few keyboard shortcuts that allow you to easily control bearblogr without having to use a mouse.
This is especially useful if you are making constant edits and need to generate markdown files frequently.
Below is a list of the currently available keyboard shortcuts for bearblogr.
| Shortcut | Action |
|---|---|
| [ SHIFT ] + M | Generates markdown file from latest version of Bear note |
| [ SHIFT ] + G | Copies generated markdown to your local Git repo (performs a pull/clone if necessary), adds a commit message, and pushes to remote (eg. publish your note) |
| [ SHIFT ] + S | Upload generated markdown to your AWS S3 bucket. This action will update existing files in the bucket with same name. |
| [ SHIFT ] + C | Copy generated markdown to local Git repo only (eg. for previewing your note locally) |
| [ CTRL ] + [ SHIFT ] + D | Removes all *.md files in the markdown cache `~/bearblogr` |
| V | View last generated markdown file in browser (or your default application used to view *.md files) |
| D | Download markdown to `~/Downloads` folder (or your default browser download folder) |
| L | Toggle debugging log |
🙏 Thanks for using bearblogr! Happy blogging! 💻
Get in touch
If you like bearblogr, drop me a line at @neooeevo. I want to hear from you!
Don’t forget tosignup for the newsletter for the updates, releases, and access to additional features!
Thanks!
While we do not anticipate any major issues with this software, we are not responsible for any damage or data loss while using bearblogr. Users who download, use, share the above app are subject to our Terms and Conditions outlined here.