There is no difference in terms of underlying functionality. Both follows a naive approach to rebuild the index for each site build, that is, the plugin will delete the existing index then recreating it. It is done so because Azure search requires the index to be rebuilt if there are changes to existing fields, it only supports incrementally adding new fields to existing indeces.

Check out the Github page (https://github.com/artchen/gatsby-plugin-azure-search) for how to use the plugin. Pull requests are welcomed to make the it better.

In the recent project to move Otakism to Gatsby and headless WordPress I discovered a pretty bad page stuck issue when integrating Disqus. Most blog posts are just fine but on a particular page Pixiv Best Artists that contains much more text and links, the page will stop rendering to wait for a particular Disqus script to finish executing.

I looked into the issue by recording a performance profile from Chrome dev tool.

The script alfalfalfa.js that blocked page rendering came from a Disqus domain c.disquscdn.com, which is separate from the main embed.js that based on my understanding renders the Disqus discussion thread. So what does this extra script do?

It turns out it is for targeting and attribution. In Disqus dashboard under Site > Advanced, there are 2 settings for Tracking and Affiliated Links:

When I turn off both checkboxes, Disqus will stop loading the alfalfalfa.js script on to the page, which then solves the issue.

Taking a closer look at what these options do, I believe the Affiliate links option is the root cause. It seems to go through all <a> tags on the page in order to append the merchant code. Their script might be using a simple loop without doing it in asynchronous batches, so when the page contains a large number of links it will make the entire page unresponsive. My Pixiv archive page does have lots of links so it unfortunately became a victim.

In conclusion, I solved the problem for myself by unchecking the affiliated link option. This is acceptable for me ’cause I don’t promote products on the site. If you do need to enable that option and you are also running into the unresponsive page issue, you might need to contact Disqus for a better solution.

My solution uses a private WordPress.com site as the back-end CMS, and a Gatsby generated static site sourcing data from the WordPress. This architecture is referred to as headless CMS nowadays. Certainly, it is not limited to the Gatsby WordPress combo. Technically any CMS with a content API can be used with any static generators to achieve this architecture. The difference comes down to how well it is supported on each side, so that we can build with minimum overhead.

I chose WordPress.com as the CMS because it is free. Another popular blogging platform Ghost also natively supports being a headless CMS. They provided good documentation as well. But it is much harder to host Ghost (stably) for free.

The choice of Gatsby mainly comes to how well it supports WordPress as a headless CMS. Gatsby supports it officially with gatsby-starter-wordpress and gatsby-source-wordpress. The former is a boilerplate app which can also be a great reference should you wish to DIY. The latter is the official plugin that wraps WordPress REST API with GraphQL that Gatsby is based on.

I don’t want to make this post a tutorial for setting up this Gatsby-Wordpress headless CMS architecture. I can’t beat the official documentation that is already very easy to read. If you want to set up something similar, just follow the links in this post. I do have a few tips that are not explicitly documented but worth sharing.

Query only the required resources

Make sure to request only the required WordPress resources to speed up Gatsby build. It does not break anything to request all of them, but considering that Netlify free tier has a limit on monthly build time, it is wise to be more frugal.

{
  options: {
    includedRoutes: [
      `**/posts`,
      `**/pages`,
      `**/categories`,
      `**/tags`,
      `**/users`,
    ],
  }
}

Paginated categories and tags page

The official gatsby-starter-wordpress has examples for categories and tags page, but those are not paginated. Here are the paginated version in gatsby-node.js:

const { paginate } = require('gatsby-awesome-pagination');
const createWordpressTags = ({ graphql, actions, publishedPosts }) => {
  return graphql(`
    {
      allWordpressTag(filter: { count: { gt: 0 } }) {
        edges {
          node {
            id
            name
            slug
          }
        }
      }
    }
  `).then(result => {
    if (result.errors) {
      result.errors.forEach(e => console.error(e.toString()))
      throw new Error(result.errors);
    }

    const tagTemplate = path.resolve('./src/templates/tag.js');
    const { createPage } = actions;
    const tags = result.data.allWordpressTag.edges;

    tags.forEach((edge) => {
      const tagPath = `/tags/${edge.node.slug}`;

      paginate({
        createPage,
        items: publishedPosts.filter(postEdge => {
          if (!Array.isArray(postEdge.node.tags)) {
            return false;
          }
          for (let tag of postEdge.node.tags) {
            if (tag.slug === edge.node.slug) {
              return true;
            }
          }
        }),
        itemsPerPage: 12,
        pathPrefix: ({ pageNumber }) => {
          return pageNumber === 0 ? `${tagPath}/` : `${tagPath}/page`
        },
        component: tagTemplate,
        context: {
          name: edge.node.name,
          slug: edge.node.slug,
        },
      });
    });
  });
};

Paginated categories work in the same way.

Set up build hook

Once your WordPress.com site is up and you have a Gatsby site deployed to Netlify, you might wonder how to trigger the build automatically. This can be easily set up with web hook.

Go to the Netlify dashboard. Under Site Setting > Build & Deploy > Build hooks, create a new build hook. Copy the generated url.

Go to the traditional WP Admin of your WordPress site. Go to Settings > Webhooks from the sidebar. Then click the Add webhook button. You will create 2 webhooks, one for publish_post, the other for publish_page. Enter the webhook url copied from Netlify. Choose anything from the fields list. It does not matter because Gatsby does not rely on these data to re-build the site.

By doing so, WordPress will invoke the Netlify build hook url, and Netlify will trigger a deployment that pulls the latest data from WordPress.

I was skeptical about the “dark mode” hype but it turned out pretty darn good with this theme. Now the hesitation is whether to make dark the new default.

Home page:

Article page:

By the way here is the simple media query that does the magic.

@media (prefers-color-scheme: dark) {
  /* Your rules */
}

Reference: https://css-tricks.com/dark-modes-with-css/

This is another quick note for my own reference. For most steps I followed this documentation: Using Cloud SQL for MySQL, but there are some gotchas that are worth noting.

Before getting into the details, here are some background information for readers. My goal is to set up a node.js application on Google Cloud App Engine. I use a MySQL instance on Cloud SQL, and I access my DB via Sequelize.

Sequelize configuration

{
  dialectOptions: {
    // socketPath: '/cloudsql/{project-id}:{region}:{cloudsql-instance-name}'
    socketPath: `/cloudsql/${process.env.CLOUD_SQL_CONNECTION_NAME}`
  }
}

Do not include host and port, or put host the same value as socketPath.

app.yaml

env_variables:
  CLOUD_SQL_CONNECTION_NAME: {project-id}:{region}:{cloudsql-instance-name}
beta_settings:
  cloud_sql_instances: {project-id}:{region}:{cloudsql-instance-name}

The beta_settings part can be easy to miss.

Permission

This part turns out unexpected, I didn’t figure it out until diving into error logs.

It seems both Cloud SQL API and Cloud SQL Admin API needs to be enabled. Both are not enabled by default. The documentation mentioned about Cloud SQL API, but I didn’t know Admin API is also required until actually try to deploy the app.

I recently installed wordpress on my EC2 host. Regret a lot that I didn’t note down the steps right away. Now I have to rely on my poor goldfish memory.

Install Packages

Note:

• I use Amazon Linux.
• I didn’t install mysql on localhost because I have an RDS instance.
• My host already has nginx installed.

sudo yum install -y php70 php70-fpm php70-gd
sudo chkconfig php-fpm-7.0 on

Configure PHP-FPM

vim /etc/php-fpm-7.0.d/www.conf

Make sure these are present and uncommented:

user = nginx
group = nginx
listen = 127.0.0.1:9000

Download WordPress

cd /var/www
wget https://wordpress.org/latest.tar.gz
tar xvf latest.tar.gz

Modify permissions. Grant folders 755 and files 644.

sudo chown nginx:nginx -R /var/www/wordpress
sudo find /var/www/wordpress -type d -exec chmod 755 {} \;
sudo find /var/www/wordpress -type f -exec chmod 644 {} \;

Configure Nginx

Create a new nginx site configuration.

vim /etc/nginx/sites-available/blog.otakism.com

With the following content.

server {
    listen 80;
    listen [::]:80;
    listen 443 ssl;
    listen [::]:443 ssl;
    
    server_name blog.otakism.com;
    root /var/www/wordpress;
    charset utf-8;
    
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$args;
    }
    
    location = /favicon.ico {
        log_not_found off;
        access_log off;
    }
    
    location ~ \.php$ {
        fastcgi_intercept_errors on;
        fastcgi_index index.php;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\. {
        deny all;
    }
    
    location ~* /(?:uploads|files)/.*\.php$ {
        deny all;
    }
    
    ssh_client_certificate /etc/nginx/ssl/cloudflare.pem;
    ssl_verify_client on;
    
    ssl on;
    ssl_certificate /etc/nginx/ssl/otakism.crt.pem;
    ssl_certificate_key /etc/nginx/ssh/otakism.key.pem;
}

Simlink the configuration file to sites-enabled.

ln -s /etc/nginx/sites-available/blog.otakism.com /etc/nginx/sites-enabled/blog.otakism.com

Restart nginx.

sudo service nginx restart

Gotchas

Make sure EC2 can talk to RDS. Set up the RDS security group to allow inbound TCP request to the db port from the EC2 host.

Heroku has always been my favorite platform for hosting prototypes and demo apps. I have 2 Ghost sites hosted on Heroku for display 2 of my Ghost themes. I haven’t touched either of them since 2016 and they have been running without a problem. However, as I checked out what has changed to Ghost since 2016, I found out the core code changes make it harder to deploy new versions (v1.0 and above) to Heroku. Fortunately there is a solution, and here is how it works.

Note that this post is very specific to my use case: upgrade a demo site from Ghost v0.11.x to v1.22.x. The solution will make some small changes to Ghost core code, which makes future upgrades harder to maintain. I am OK with it because I am not going to frequently update these demo sites. But if you are deploying serious projects, or a frequently updated blog, my solution is not great.

Before Getting Started

Make sure you have git, Node.js and npm.

Install Heroku CLI: https://devcenter.heroku.com/articles/heroku-cli

Download Ghost

Download the .zip version of Ghost source code from https://ghost.org/developers/. Unzip it to a folder.

Initialize Git Project

I highly recommend you not do the git push --force. I did because I really don’t care.

git init
git add -A
git commit -m "init project"
git remote add origin <your-heroku-git-url>
git push --force --set-upstream origin master

Set up MySQL

Ghost v1+ only officially supports MySQL. So you need to deploy a MySQL add-on. Either do it via Heroku console or using this command:

heroku addons:create cleardb:ignite

Find database connection credentials by going to Settings tab and look for the CLEARDB_DATABASE_URL config variable, or using this command:

heroku config:get CLEARDB_DATABASE_URL

It should look like mysql://<db-user>:<db-password>@<db-host>/<db-ame>;

Set some more config variables:

heroku config:set \ 
database__connection__user=<db-user> \ 
database__connection__password=<db-password> \ 
database__connection__host=<db-host> \
database__connection__database=<db-name> \
database__pool__max=2

These config variables will make sure the database connection credentials be picked up by Ghost.

Run the following command to initialize the database. You can also run it from Heroku console. Click the ‘More’ dropdown and choose Run Console, type in bash and hit enter. You will be able to run shell commands in your dyno.

heroku run "knex-migrator init"

It will fail, at least it did it to me. The error will look like Error: Tarn: opt.max must be an integer > 0.

The solution is to change a core file core/server/config/index.js, look for this snippet:

nconf.env({
  separator: '__'
});

Change it to:

nconf.env({
  separator: '__',
  parseValues: true
});

Thanks to this Github issue: https://github.com/tgriesser/knex/issues/2570

Configurate Ghost

heroku config:set server__host=0.0.0.0
heroku config:set url=https://yabu.rakugaki.me

Add the following to core/server/config/index.js so that Ghost can pick up the $PORT env variable.

nconf.set('server', {
  port: process.env.PORT
});

Now do another deployment and the Ghost site should be running on Heroku.

Element is another minimal theme for Hexo.

Dependencies

This theme depends on the following Hexo plugins:

• hexo-generator-tag
• hexo-generator-feed
• hexo-renderer-ejs
• hexo-renderer-less
• hexo-renderer-marked
• hexo-pagination
• hexo-all-minifier
• hexo-autoprefixer
• hexo-front-matter

For local search, you also need hexo-generator-json-content and add configuration to your global _config.yml if needed, refer to hexo-generator-json-content github repository.

Customization

Element is customizable via the _config.yml in the theme directory.

Element also depends on the global _config.yml. For example:

• Set disqus_shortname field to your disqus short name.
• Set theme field to hexo-theme-element.
• Set title, url, author and description.

In addition to these settings, you may also want to edit/replace the following files:

• Replace the author avatar: source/img/avatar.png.
• The font used on Artifact.me is Futura PT. I include it via Adobe Typekit. You need to use your own web font service, or go with the default Lato via Google Font. Details in layout/_partial/head.ejs.

This theme currently supports 4 search services:

• Google custom search
• Hexo Local search (hexo-json-content)
• Algolia search
• Microsoft Azure search

Setup guide for searching is availble here: universal-search.

Demo

Artifact.me

Copyright

Public resources used in this theme:

• icomoon
• normalize.css
• Google Fonts – Lato

Copyright © Art Chen

Please do not remove the "Theme by Art Chen" text and links.

This is the 5th article in a series that covers the steps to add searching to Ghost, Hexo or any general website using APIs provided by various services.

The latest version of Universal Search is available on Github at https://github.com/artchen/universal-search.

We have covered UI and common logics in the first article. In this article we are going to explore Azure Search.

Register for Service

First of all, register an Azure account or just use your Microsoft account (outlook.com, hotmail.com, etc), and start your free trial.

Go to the dashboard, and create a new service.

Search "Azure Search".

Create a free Azure Search service. The creation might take a few minutes.

Go to the control panel of your new Azure Search service. Choose Keys to reveal admin keys. Note down your primary admin key. We need this admin key to access the REST API.

On the same panel, select "Manage query keys" and create a new query key. Note it down again. This query key will be used on the front-end to query your created index.

Generate and upload data

Just like Algolia, Azure Search does not index your website automatically. Instead, it requires the users to create indexes and upload data.

In this tutorial, I will use hexo-azuresearch, a plugin that I wrote, to demonstrate how to integrate Azure Search with Hexo. If your website is on other platforms, Azure provides detailed documentation about all the APIs it supports so it should not be too complicated to write your own indexer and data uploader.

A heads up notice for non-English users, at this point I cannot get Azure Search to work with other languages. I will look into this issue.

Hexo

npm install --save hexo-azuresearch

In your global _config.yml, add the following configuration:

In order for our front-end to work, you must include title, excerpt:strip and path. The other fields only help with searching accuracy.

# Azure Search
AzureSearch:
  serviceURL: "https://<your-service-name>.search.windows.net"
  indexName: "<your-index-name>"
  adminKey: "<your-azure-search-admin-key>"
  analyzer: "zh-Hans.lucene" # optional
  fields:
    - title
    - excerpt:strip
    - content:strip
    - path
    - permalink

Then run the following command to index and upload data:

hexo azuresearch

Ghost

Unfortunately there is no existing support for Ghost.

Build the class

This section is more of a development note. Plugin users don’t have to read it.

The class for Azure Search is very similar to the one we built for Google Custom Search Engine. The only differences are the credentials and data formats.

https://gist.github.com/artchen/a480bf1e066ca7412a2f20c40961782d.js

Enable your search

var customSearch = new AzureSearch({
  serviceName: AZURE_SERVICE_NAME,
  indexName: AZURE_INDEX_NAME,
  queryKey: AZURE_QUERY_KEY
});

This is the 4th article in a series that covers the steps to add searching to Ghost, Hexo or any general website using APIs provided by various services.

The latest version of Universal Search is available on Github at https://github.com/artchen/universal-search.

We have covered UI and common logics in the first article. This time we are going to explore Algolia, a wonderful tool to index your website.

Create an index

First of all you need to register at www.algolia.com.

Algolia will guide you to create the first application, you can choose a server location based on your target users.

If a tutorial pops up, you can skip it. Go straight to create an index.

Go to API Keys and find your credentials. You will need the Application ID, the Search-only API key and the Admin API key in the following sections.

Generate and upload data

Algolia requires users to upload their search index data either manually or via provided APIs. They provide many integration sdks available at https://www.algolia.com/integrations. Most of them are well documented.

If your website have back-end (database, server logics, etc), most likely Algolia already provide an server-side client. Just go ahead and follow their instructions.

If you are using a static site generator like Hexo, you might need to code a plugin so that every time you generate the site, the program will also upload a copy of index to Algolia. Currently the only official Algolia plugin for static site generator is Jekyll.

I will only cover the integration with Hexo here since it is not yet officially supported.

Hexo

Install and configure hexo-algoliasearch in your Hexo directory. This plugin will index your site and upload selected data to Algolia.

npm install --save hexo-algoliasearch

In your global _config.yml, add the following configuration:

In order for our front-end javascript to work, you must include title, excerpt:strip and path. The other fields only help with searching accuracy.

# Algolia
algolia:
  appId: "YOUR ALGOLIA APPLICATION ID"
  apiKey: "YOUR ALGOLIA SEARCH-ONLY API KEY"
  adminApiKey: "YOUR ALGOLIA ADMIN API KEY"
  chunkSize: 5000
  indexName: "YOUR INDEX NAME"
  fields:
    - title
    - excerpt:strip
    - path
    - content:strip
    - permalink

Then run the following command to upload data:

hexo algolia

Ghost

Unfortunately there is no existing support for Ghost.

Build the class

This section is more of a development note. Plugin users don’t have to read it.

The class for Algolia is very similar to the one we built for Google Custom Search Engine. The only differences are the data formats.

For consistency of UI, I didn’t use the javascript client provided by Algolia, which is implemented as autocomplete instant search.

https://gist.github.com/artchen/231eee1223539cfdd094caa07bd6bec5.js

Enable your search

var customSearch = new AlgoliaSearch({
  apiKey: ALGOLIA_API_KEY,
  appId: ALGOLIA_APP_ID,
  indexName: ALGOLIA_INDEX_NAME
});

This is the 3rd article in a series that covers the steps to add searching to Ghost, Hexo or any general website using APIs provided by various services.

The latest version of Universal Search is available on Github at https://github.com/artchen/universal-search.

We have covered UI and common logics in the first article. This time we are going to explore Hexo local search. If you website is not generated by Hexo, you don’t necessarily need to read this article.

Basic Idea

Static site generator like Hexo does not rely on any database. Instead they pre-generate all pages and save them as individual html files. If we want to add search ability without using 3rd-party services, we will have to generate the "database" ourselves. In this case, the "database" is a index file that contains essential information of pages and posts. When the user submit a search request, the front-end javascript will download this index file, and searching for relevant items.

Generate Index File

There are several Hexo generators that does this for us. I use hexo-generator-json-content by alexbruno for this project.

To install this plugin, first navigate to your Hexo directory, then

npm install --save hexo-generator-json-content

Then edit the global _config.yml, add the following configuration:

jsonContent:
  meta: false
  keywords: false # (english, spanish, polish, german, french, italian, dutch, russian, portuguese, swedish)
  pages:
    title: true
    slug: false
    date: false
    updated: false
    comments: false
    path: true
    link: false
    permalink: true
    excerpt: false
    keywords: false
    text: false
    raw: false
    content: true
  posts:
    title: true
    slug: false
    date: false
    updated: false
    comments: false
    path: true
    link: false
    permalink: true
    excerpt: false
    keywords: false
    text: false
    raw: false
    content: true
    categories: false
    tags: false

The plugin should be good to go. From now on, every time hexo generate is executed, a content.json file will be generated in the public directory.

Build the class

This section is more of a development note. Plugin users don’t have to read it.

The class for Hexo local search is similar to the one we created for Google Custom Search Engine except this time we need a contentSearch(post, queryText) function to manually account for the keyword searching.

I adopted this searching algorithm from http://hahack.com/codes/local-search-engine-for-hexo/. It was pretty simple and clean.

https://gist.github.com/artchen/dd07cb1552e0335cdda6c9f692cbca13.js

Enable your search

Initialize an instance of the HexoSearch class:

var customSearch = new HexoSearch({
  endpoint: "<path-to-your-content.json>" # optional
});

This is the 2nd article in a series that covers the steps to add searching to Ghost, Hexo or any general website using APIs provided by various services.

The latest version of Universal Search is available on Github at https://github.com/artchen/universal-search.

We have covered UI and common logics in the previous article. This time we are going to integrate Google Custom Search Engine.

Get Engine ID

Go to https://cse.google.com. Click the add button.

Go to next. Enter your website domain. Then click the create button.

On the congratulations screen, click Control Panel.

On the control panel, click Search Engine ID, note down the ID in the popup modal.

Get API Key

Go to Google API Console. You may need to register first. Click ENABLE API.

Search for "custom search", click on the first result.

On the Custom Search API page, click on Credential in the left side bar.

On the Credential page, click create credential, then choose API Key.

On the popup modal, choose Browser key.

Name you API key and specify any URL wildcard as authorized referrers, then click create.

You will be prompted the API key.

Build the class

This section is more of a development note. Plugin users don’t have to read it.

The GoogleCustomSearch class should inherit the SearchService class that we built in the previous article so that it has all the functions that control common data logics and the UI.

There are only 3 functions to customize:

• buildResultList(data): traverse the result array, pass url, title and digest to the common buildResult() function to generate HTML markups.
• buildMetadata(data): generate metadata to enable pagination.
• query(queryText, startIndex, callback): send Ajax GET request to the Google Custom Search endpoint to get search results.

In detail, we coded a class like this:

https://gist.github.com/artchen/212e08ff3ae2290c7b6c0dcfb32a407f.js

Enable your search

It should be as simple as initialize an instance of the GoogleCustomSearch class with your credentials:

var customSearch = new GoogleCustomSearch({
  apiKey: GOOGLE_CUSTOM_SEARCH_API_KEY,
  engineId: GOOGLE_CUSTOM_SEARCH_ENGINE_ID
});

This is the 1st article in a series that covers the steps to add searching to Ghost, Hexo or any general website using APIs provided by various services.

The goal of this series is to eventually create a javascript package that allows users to add searching to their websites by only copy-pasting code snippets and changing some configurations.

I name the series "universal search" because these techniques are meant to work on any website. In reality, some of them require additional plugins to be installed, some of them may only apply to a few platforms. What I am trying to do here is to provide as many options as possible so that users can find at least one solution that works.

Before reading

The latest version of Universal Search is available on Github at https://github.com/artchen/universal-search, feel free to clone and install.

This article discusses my design of the plugin. If you only want to use it without knowing everything behind the scene, you can go ahead to one the of the following tutorials to setup individual search services:

• Google Custom Search Engine
• Hexo Local Search – Hexo only
• Algolia Search
• Azure Search
• Baidu Search

Basic Workflow

• Register a 3rd-party searching service, get the credentials (API Key, ID, etc).
• Send Ajax GET requests to some endpoint, get response in JSON format.
• Parse the response if necessary.
• Render the results on UI.

Common UI

Though I always advocate original and customized design, this time I am going to use the same common UI for some consistency. This interface is independent of whatever 3rd-party search service we choose.

https://gist.github.com/artchen/4a961c7ac9d6b9da188868c0f29a15d4.js

This markup will be compressed and embedded into the javascript. When the plugin is initialized, the markup will be inserted into <body>.

Common Logic

The javascript part of universal search should take care of 3 main aspects:

• Query for search results.
• Parse results.
• Render UI.

We already decided that the UI should be the same across services. So the following UI interactions should be defined as common functions.

• onSubmit(event): when the user submit the search form, open modal and query.
• onNextPage(): when the user request the next page, fetch next page.
• onPrevPage(): when the user request the previous page, fetch previous page.
• close(): when the user close the modal, fade out the modal.
• uiBeforeQuery(): hide the result container, show loading animation.
• uiAfterQuery(): hide loading animation, scroll result container to top, fade in the results.
• startLoading(): start the timer for loading bar animation.
• stopLoading(): stop the timer for loading bar animation.

The query and parsing need to be defined on a per service basis because they apparently have different formats of API and response data. But we can centralize the following functions.

• onQueryError(queryText, status): empty result container, generate error messages and render in error container.
• buildResult(url, title, digest): generate html for one result.

Most importantly, there should be init() and destroy():

• destroy(): unregister event handlers, clear markups.
• init(): register event handlers.

All the functions listed above are common logics that goes into a super class called SearchService.

Here is the result:

https://gist.github.com/artchen/a24102f119cf67e385db7cfa39a9c812.js

These conclude the high level design and common part of universal search.

You can now proceed to one of the following articles to integrate the search service of your choice:

• Google Custom Search Engine
• Hexo Local Search – Hexo only
• Algolia Search
• Azure Search
• Baidu Search

Memory is a minimal theme for Hexo.

The theme is available on github at https://github.com/artchen/hexo-theme-memory

This theme is also available on:

• Ghost version: ghost-theme-memory

Dependencies

This theme depends on the following Hexo plugins to work correctly:

• hexo-generator-tag
• hexo-renderer-ejs
• hexo-renderer-less
• hexo-renderer-marked
• hexo-pagination

Please make sure these plugins are installed before generate the site.

Customization

The theme is customizable via _config.yml file under the theme directory.

The global _config.yml for Hexo may also be modified. In particular:

• Add/modify disqus_shortname field, the value set to your Disqus short name
• Change theme field to hexo-theme-memory

In addition to these settings, users may also want to edit/replace the following files:

• Replace the site logo: source/images/logo.png, source/images/logo.psd
• The search feature uses swiftype. Please follow their instruction to setup yours.
• The icon fonts are from icomoon.

Demo

Copyright

Public resources used in this theme:

• icomoon
• normalize.css
• fitvids.js

Copyright © Art Chen

Please do not remove the "Theme Memory designed by Art Chen" text and links.

Memory is a minimal theme for Ghost. I am working on a Hexo version, too.

The theme is now available at https://github.com/artchen/ghost-theme-memory.

This theme is also available on:

• Hexo version: hexo-theme-memory

Production

If you are going to use the theme directly (without much customization).

cd /content/themes/
git clone https://github.com/artchen/ghost-theme-memory.git

The version shared via Github is used on otakism.com, my blog. There are quite a few things hard-coded into the template that you’ll need to customize. Including but not limited to:

• The site logo: assets/img/logo.png
• The short text under the logo: partials/header.hbs
• Disqus integration: page.hbs, post.hbs
• Social account links: partials/footer.hbs

The search feature relies on swiftype. Please follow their instruction to set up your own searches.

The fonts are from Typekit. If you are not using typekit, please remove corresponding code is in default.hbs.

Development

Clone the repository.

cd /content/themes/
git clone https://github.com/artchen/ghost-theme-memory.git memory

Install gulp, bower and npm before proceed.

Install and build the app:

cd ./ghost-theme-memory
npm install
bower install
gulp

At this point your development environment is ready.

Update

cd /content/themes/ghost-theme-memory/
git pull

Demo

Visit my blog (in Chinese) for a demo of tis theme. http://otakism.org.

Screenshot

Copyright

Public resources used in this theme:

• icomoon
• normalize.css

Copyright © Art Chen

Please do not remove the "Theme Memory designed by Art Chen" text and links.

Gulp is a great build tool for web applications. In this article I am sharing some gulp scripts that I found really useful.

Installing Gulp

Node.js needs to be installed prior to installing gulp. Once Node.js is ready on your machine, run this command to install gulp:

sudo npm install --global gulp-cli

This will install the gulp command line tools globally, such that the gulp command can be invoked throughout the computer.

Create a Gulp Project

Change directory to the project’s root.

npm init

First of all, initialize npm, set the project name, version, author, etc. After the setup, package.json will be created.

npm install gulp --save-dev

Install gulp for the project. --save-dev make sure that gulp is logged in package.json as a development dependency. This is particularly useful when we need to port the project to another computer. With all the dependencies logged in package.json, we just run npm install to get them back, instead of install each of them again, or copy the gaint node_modules folder around.

Project Structure

For an Angular.js application with gulp as the build tool, I usually setup the project directory like this:

|- project/                
  |- bower_components/
  |- dist/
  |- node_modules/    
  |- src/
    |- css/              # vendor css
    |- less/             # my less source code
    |- img/
    |- js/               # my javascript source code
    |- vendor/           # vendor js
    |- views/            # angular templates
    |- index.html
  |- bower.json
  |- gulpfile.js
  |- package.json

A simple gulpfile.js

Here comes the fun part. A basic gulpfile looks like this:

// require gulp dependencies
var gulp = require('gulp');

// declare a gulp task
gulp.task('task_name', function() {
  // task pipelines
});

The tasks can be run in command line like:

gulp task_name

Define Paths

Define a path object to keep track of all the source code in the project, making it easier for reference in various gulp tasks. For one of the angularjs application, I had the following paths:

var path = {
  // template markups
  HTML: [
    'src/*.html',
    'src/views/**/*.html',
    'src/views/*.html'
  ],
  // my js source code
  JS: [
    'src/js/**/*.js'
    'src/js/*.js',
  ],
  // all less files (for changes monitoring purpose)
  LESS_ALL: [
    'src/less/*.less'
  ],
  // main less file (others are imported in style.less)
  LESS: [
    'src/less/style.less'
  ],
  // images
  IMG: [
    'src/img/**'
  ],
  // vendor css
  CSS: [
    'src/css/*.css'
  ],
  // vendor js
  VENDOR: [
    'bower_components/angular/angular.js',
    'bower_components/angular-animate/angular-aria.js',
    // ...and more
  ],
  DIST: [
    './dist'
  ]
};

Installing Gulp Plugins

There are tons of useful gulp plugins to explore. Gulp plugins can be installed by

npm install <plugin-name> --save-dev

For example, to install gulp-connect:

npm install gulp-connect --save-dev

Useful Gulp Tasks

Here I only introduce some gulp tasks that I found helpful in angularjs development.

Spin up a erver for dist.

var connect = require('gulp-connect');

gulp.task('connect', function() {
  connect.server({
    root: 'dist',
    port: 4000
  });
});

Clean up distribution directory.

var connect = require('gulp-clean');

gulp.task('clean', function() {
  return gulp.src('./dist/*', {force: true})
    .pipe(clean());
});

Use JSLint.

var jshint = require('gulp-jshint');

gulp.task('lint', function() {
  return gulp.src(path.JS)
    .pipe(jshint())
    .pipe(jshint.reporter('default'))
    .pipe(jshint.reporter('fail'));
});

Copy over CSS and HTML

gulp.task('css', function () {
  gulp.src(path.CSS)
    .pipe(gulp.dest(path.DIST + '/css'));
});

gulp.task('html', function () {
  gulp.src(path.HTML, {base: 'src'})
    .pipe(gulp.dest(path.DIST));
});

Compile, minify and copy Less.

var less = require('gulp-less');
var lessDependents = require('gulp-less-dependents');
var minifyCSS = require('gulp-minify-css');

gulp.task('less', function () {
  gulp.src(path.LESS)
  	.pipe(lessDependents())
    .pipe(less())
    .pipe(minifyCSS())
    .pipe(gulp.dest(path.DIST + '/css'));
});

Merge, uglify and copy js files.

var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var ngAnnotate = require('gulp-ng-annotate');
var sourcemaps = require('gulp-sourcemaps');

gulp.task('js', function () {
  gulp.src(path.JS)
  	.pipe(sourcemaps.init())
		  .pipe(concat('app.js'))
		  .pipe(ngAnnotate())
		  .pipe(uglify())
		.pipe(sourcemaps.write())
    .pipe(gulp.dest(path.DIST + '/js'));
});

gulp.task('vendor', function () {
	gulp.src(path.VENDOR)
		.pipe(concat('vendor.js'))
		.pipe(ngAnnotate())
		.pipe(uglify())
    .pipe(gulp.dest(path.DIST + '/js'));
});

Compress images.

var imagemin = require('gulp-imagemin');

gulp.task('img', function(){
  gulp.src(path.IMG)
    .pipe(imagemin())
    .pipe(gulp.dest(path.DIST + '/img'));
});

Watch changes and automate tasks.

var watch = require('gulp-watch');

gulp.task('watch', function () {
  gulp.watch(path.LESS_ALL, ['less']);
  gulp.watch(path.VENDOR, ['vendor']);
  gulp.watch(path.JS, ['lint', 'js']);
  gulp.watch(path.HTML, ['html']);
  gulp.watch(path.IMG, ['img']);
});

Default task.

var all_tasks = ['lint', 'css', 'less', 'vendor', 'js', 'html', 'img'];

gulp.task('default', all_tasks);

A More Complete gulpfile.js

/* gulp dependencies */
var gulp = require('gulp');
var less = require('gulp-less');
var watch = require('gulp-watch');
var imagemin = require('gulp-imagemin');
var connect = require('gulp-connect');
var concat = require('gulp-concat');
var sourcemaps = require('gulp-sourcemaps');
var uglify = require('gulp-uglify');
var ngAnnotate = require('gulp-ng-annotate');
var minifyCSS = require('gulp-minify-css');
var lessDependents = require('gulp-less-dependents');
var clean = require('gulp-clean');
var bower = require('gulp-bower');
var concat_vendor = require('gulp-concat-vendor');
var jshint = require('gulp-jshint');

/* path def */
var path = {
  HTML: [
  	'src/.htaccess', 
  	'src/*.html', 
  	'src/views/**/*.html', 
  	'src/views/*.html', 
  	'src/favicon.png'
  ],
  JS: [
  	'src/js/*.js', 
  	'src/js/**/*.js'
  ],
  CSS: [
	  'src/css/*.css'
  ],
  LESS: [
  	'src/less/style.less'
  ],
  LESS_ALL: [
  	'src/less/*.less'
  ], 
  IMG: [
  	'src/img/**'
  ],
  VENDOR: [
  	'bower_components/angular/angular.js', 
		'bower_components/angular-animate/angular-animate.js', 
		'bower_components/angular-aria/angular-aria.js', 
		'bower_components/angular-messages/angular-messages.js',
		'bower_components/angular-sanitize/angular-sanitize.js',  
		'bower_components/angular-ui-router/release/angular-ui-router.js'
    // ...and more
	],
  DIST: './dist'
};

/* spin up distribution server */
gulp.task('connect', function() {
	connect.server({
		root: 'dist',
		port: 4005
	});
});

/* clean up dist dir */
gulp.task('clean', function() {
	return gulp.src('./dist/*', {force: true})
		.pipe(clean());
});

/* jslint for debugging */
gulp.task('lint', function() {
  return gulp.src(path.JS)
    .pipe(jshint())
    .pipe(jshint.reporter('default'))
    .pipe(jshint.reporter('fail'));
});

/* move css */
gulp.task('css', function () {
  gulp.src(path.CSS)
    .pipe(gulp.dest(path.DIST + '/css'));
});

/* compile less */
gulp.task('less', function () {
  gulp.src(path.LESS)
  	.pipe(lessDependents())
    .pipe(less())
    .pipe(minifyCSS())
    .pipe(gulp.dest(path.DIST + '/css'));
});

/* concat and compress app scripts */
gulp.task('js', function () {
  gulp.src(path.JS)
  	.pipe(sourcemaps.init())
		  .pipe(concat('app.js'))
		  .pipe(ngAnnotate())
		  .pipe(uglify())
		.pipe(sourcemaps.write())
    .pipe(gulp.dest(path.DIST + '/js'));
});

/* concat vendor dependencies */
gulp.task('vendor', function () {
	gulp.src(path.VENDOR)
		.pipe(concat('vendor.js'))
		.pipe(ngAnnotate())
		.pipe(uglify())
    .pipe(gulp.dest(path.DIST + '/js'));
});

/* copy over markups */
gulp.task('html', function(){
  gulp.src(path.HTML, {base: 'src'})
    .pipe(gulp.dest(path.DIST));
});

/* compress images */
gulp.task('img', function(){
  gulp.src(path.IMG)
    .pipe(imagemin())
    .pipe(gulp.dest(path.DIST + '/img'));
});

/* watch all changes */
gulp.task('watch', function () {
  gulp.watch(path.LESS_ALL, ['less']);
  gulp.watch(path.VENDOR, ['vendor']);
  gulp.watch(path.JS, ['lint', 'js']);
  gulp.watch(path.HTML, ['html']);
  gulp.watch(path.IMG, ['img']);
});

/* defualt */
gulp.task('default', all_tasks);

MAMP is a great GUI tool for creating server on localhost. But the free virsion of it only has very basic configurations. For example, creating a virtual host is not included. So I have to write the configurations on my own.

This article is based on Windows OS. Setup on Mac OS should be similar.

Why Virtual Hosts

Question: Why do we need to virtual hosts anyway? Answer: it simplifies your testing and developing. When developing a website, I want to visit it via something like http://test.local, rather than http://localhost/test/. The benefit of the former option is not just that it looks more like a real URL, or it is shorter. By creating test.local as the local domain, the root directory for your site is configured to any location your would like it to be, so there is no more hazard of nested path.

Modify Hosts

First, add the desired domain to the system’s host file. It is located at C:\Windows\System32\drivers\etc\hosts.

Add this line:

127.0.0.1		test.local

You can replace test.local with almost anything of your choice.

Modify Apache Configuration

Modify C:\MAMP\conf\apache\httpd.conf.

Find this line:

# Virtual Hosts
# Include /Applications/MAMP/conf/apache/extra/httpd-vhosts.conf

Change it to

# Virtual Hosts
Include C:\MAMP\conf\apache\httpd-vhosts.conf

Create Virtual Host Configuration

Now create the configuration file httpd-vhosts.conf.

NameVirtualHost *:80

<VirtualHost *:80>
    DocumentRoot 'C:\MAMP\htdocs'
    ServerName localhost
</VirtualHost>
 
<VirtualHost *:80>
    DocumentRoot 'C:\MAMP\htdocs\test'
    ServerName test.local
</VirtualHost>

Start MAMP, your site should be available at http://test.local.

Recently I switched from Linode to DigitalOcean because of some rumor that Linode website is blocked in China. Here is a memo of how I migrated a Ghost blog, otakism.org.

Some content came from several tutorials from DigitalOcean community. Credits are given at the end of this article.

Install Nginx

Install Nginx via apt-get.

sudo apt-get update
sudo apt-get install nginx

Create Site Directories

I prefer /var/www as the root directory. To do that I created the following folders to hold my website files.

sudo mkdir -p /var/www/rakugaki.me/html
sudo mkdir -p /var/www/otakism.org/html
sudo chown -R $USER:$USER /var/www/rakugaki.me/html
sudo chown -R $USER:$USER /var/www/otakism.org/html
sudo chmod -R 755 /var/www

Create Server Block Files

Server blocks configure ports and root directories for each website, as well as details about how they should be served.

Here I used rakugaki.me as the default domain of my server.

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/rakugaki.me
sudo vim /etc/nginx/sites-available/rakugaki.me

Change the configuration like this:

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /var/www/rakugaki.me/html;
    index index.html index.htm;

    server_name rakugaki.me, www.rakugaki.me;

    location / {
        try_files $uri $uri/ =404;
    }
}

Then I created the second server block file for otakism.org. Since it is a Ghost blog, the file should be like this:

server {
    listen 80;
    listen [::]:80;
    server_name otakism.org;
    location / {
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   Host      $http_host;
        proxy_pass         http://127.0.0.1:2368;
    }
}

The files are done but we are not done. Enable the server block files.

sudo ln -s /etc/nginx/sites-available/rakugaki.me /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/otakism.org /etc/nginx/sites-enabled/

Delete the default site generated by Nginx.

sudo rm /etc/nginx/sites-enabled/default

Restart Nginx to apply new settings.

sudo service nginx restart

Install Ghost

Prerequisites first. Ghost requires Node.js and npm. These can be installed in various ways. Refer to this article for more options.

sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install npm

Download Ghost. Details about the remaining steps in this chapter can be found in the official guide at Ghost.org.

sudo apt-get update
sudo apt-get install zip wget

cd /var/www/otakism.org/html
sudo wget https://ghost.org/zip/ghost-latest.zip
sudo unzip -d ghost ghost-latest.zip

Install it.

cd ghost/
sudo npm install --production

Configure Ghost

Change the url and/or port under production section.

sudo cp config.example.js config.js
sudo vim config.js

I also needed to migrate data, images and themes. Copy or replace them under content/.

Keep Ghost Running

Create upstart configurations to make the ghost blog start on system boot. In this way I can also manage my ghost blog as a service.

sudo /etc/init/vim ghost-otakism.conf

Paste the following lines.

# ghost-otakism

start on startup

script
    cd /var/www/otakism.org/html/ghost
    npm start --production
end script

Finally I can summon my ghost.

sudo service ghost-otakism start

Contents about Nginx setup credits to Justin Ellingwood, original post at How To Set Up Nginx Server Blocks (Virtual Hosts) on Ubuntu 14.04 LTS.

This is a memo of how to setup Ruby-on-Rails on Mac OS X 10.11. Especially, to get it work on RubyMine 8.0.3.

The following process might not be the solution for everyone.

Command-Line Tools

First of all, make sure developer command-line tools is installed.

xcode-select --install

If it is already installed, expected output should be:

xcode-select: error: command line tools are already installed, use "Software Update" to install updates

Homebrew

Install Homebrew:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Mac OS X 10.11 comes with version 2.0.0 of Ruby so this command should work.

Then we can install almost all the packages we need via homebrew.

Ruby

Use the officially recommended way to manage ruby versions with rbenv.

brew install rbenv ruby-build
rbenv install 2.2.4
rbenv global 2.2.4

Check version:

ruby -v

Dependencies

If I remember correctly.

brew update
brew upgrade
brew install libxml2 libxslt libiconv
gem install nokogiri -- --use-system-libraries --with-xml2-include=/usr/include/libxml2 --with-xml2-lib=/usr/lib/
brew install mysql
gem install mysql

Fact is a simple but powerful theme for Hexo. It comes with integration of tags, categories, archive and table-of-contents. The style design is inspired by V2EX.

The theme is available on my Github as a public repository hexo-theme-fact.

Installation

I assume you already have a Hexo blog initialized.

cd /themes
git clone https://github.com/artchen/hexo-theme-fact.git fact

Don’t forget to modify _config.yml under root directory of Hexo blog. Change theme to Fact.

theme: fact

Configuration

Some configuration can be found in _config.yml under the themes/fact directory.

Update

cd /themes/fact
git pull

Fonts

I used Futura for text, and Inconsolata for source code. Both of them are hosted on Typekit.

If you do not use Typekit, here are the necessary steps to switch to other services:

1. In layout/_partial/head.ejs, delete the lines that include the typekit library, then include necessary files from your choice of web fonts (eg: Google Font).
2. In source/css/_sass/style.scss, change the font macros to your choices.

Screenshot