IMPORTANT: this is a still an early version of Vocal, with some missing features and most probably some bugs! Here is what is missing for the version 0.0.1 to be ready. That version is basically the MVP for my own blog, then I will work on 0.0.2 and 0.1. You can look at the basic Kanban board I've setup to know where I'm at: https://waffle.io/jipiboily/vocal.
- Everything is in Markdown, side by side edit + preview in admin
- Supports GFM
- Vocal does not aim for minimal requirements, so it might not be as easy to mount into an existing app as Monologue is
- I will not try to get anything working for old browsers
- admin is built with Ember
- I want it to be fast, at least (in future versions)
- I dream about a dashboard with some basic analytics (in future versions)
- I want a couple of features to help reader retention (reading suggestions when reaching the end being one)
- It will have basic support for "static" pages for stuff like about pages
- I <3 keyboard shortcuts, so there will be some in admin (in future versions)
- No user management UI for now, single user, basically (well, not exactly, but this would not be usable in serious situations with multiple users)
- Assuming Postgres, but should work with MySQL
- Create a new Rails app:
rails new my-vocal-blorgh.
source 'https://rails-assets.org'right after
source 'https://rubygems.org'in your
gem 'vocal'to your
- Add the theme Gemfile, default being
bundle exec rake vocal:install:migrationsto copy Vocal's migration into your project.
- Edit your database.yml with your database information.
config/initializers/vocal.rband set the default theme:
Vocal.config.theme.name = 'default' # default is the name of the theme.
bundle exec rake db:create && bundle exec rake db:migrate.
mount Vocal::Engine => "/"
open http://0.0.0.0:3000/adminshould get you to the admin signup screen (only possible when there is no admin user yet) and then the admin.
Now, jump to the full configuration...
For now, see this example.
How to customize Vocal, or a theme?
In terms of customizations, you have a few options:
- create your own theme.
- add just some custom CSS or JS, if the theme supports it (the default one does.)
- use Deface. How? See the next section.
- override any files, using the same path as the original one and it should be used instead of the original one.
Customizing with Deface
gem 'deface' in your Gemfile, then look at the doc. You can do things like "insert X before this" and that kind of stuff, replace, and all. It's pretty sweet if you have mostly minor tweaks that would make overriding things overkill or "dangerous".
A few things to note:
- disable it in prod. Run
bundle exec rake deface:precompileand add the compiled views to your repo, or run this task once deployed, depending on your deployment setup.
- this is specific to Vocal, but the way theming works right now requires a little tweak so Deface will find your theme's views. Add this to your
environment.rb, at the end. I understand this is hacky, but this is what I came up with for now, suggestions welcomed, but there is a matter of when things get loaded and all.
# This is so that the Deface precompile task can find it ActionController::Base.append_view_path(Vocal::Theme::Helpers.theme_files_path)
git clone firstname.lastname@example.org:jipiboily/vocal.git cd vocal bundle install cp spec/dummy/config/database.sample.yml spec/dummy/config/database.yml cd spec/dummy bundle exec rake app:vocal:install:migrations bundle exec rake db:setup RAILS_ENV=test bundle exec rake db:setup
Boot your server and go to the admin: http://localhost:3000/admin.
Optional setup steps
I personally use pow, so I also add this:
ln -s ~/code/vocal/spec/dummy ~/.pow/vocal open http://vocal.dev/admin