Skip to content

getting-started.md

Latest commit

 

History

History
207 lines (134 loc) · 6.2 KB

getting-started.md

File metadata and controls

207 lines (134 loc) · 6.2 KB
Raw

NOTE: This document is cloned from cssjpn/blog-example

Getting Started

This guide covers getting started with the blog-example.

Installation

In this Getting Started, you need git, docker and docker-compose.

Git

Docker

Make sure the following commands are successful:

$ git
$ docker
$ docker-compose

Setup a new CSS Blog

Creating a blog repository from a template

Navigate to the cssjpn/blog-example page. Above the file list, click Use this template.

Select your organization from Owner menu, and type a name for your blog repository (ex. blog). Click Create repository from template.

Cloning a repository

# Move to your working directory
$ cd {YOUR_WORKING_DIR}

# Cloning a blog repository
$ git clone git@github.com:${YOUR_ORGANIZATION}/blog.git
$ cd blog

Initialize blog theme

Blog theme (.css, .js, etc...) is configured as git submodule. This example is using jpazureid/hexo-theme-jpazure

# Initialize and Update themes
$ git submodule update -i

Customize site configuration file

You can configure most settings here.

# edit config with your favorite editor
$ code _config.yml
$ vim _config.yml
...

If you want to modify the blog from the template design to fit your team, you need to change the following settings.

  • title and subtitle
  • url and github
  • root
  • disclaimer

title and subtitle:

By changing the title and subtitle, you can change the wording of the top of the blog as shown in the image

url and github:

Write the URL of the Github Pages of your blog in "url:". Also, in "github:", Describe the github repository of your blog.

The Github Pages URL you would specify as "url:" is normally https://<organization or account name>.github.io/<repo name>/.

The Github repo name you would specify as "github:" is normally https://github.com/\<organization or account name>/<repo name>/

root:

If the repo name is not /blog, specify that name for root. repo name and root must be the same.

disclaimer

A disclaimer will be placed at the end of every article, which can be disabled by setting disableDisclaimer: true.

Writing blog articles

Now you can start writing articles!

# Create new branch
$ git checkout -b add_article

# Create or Edit articles with your favorite editor
$ vim articles/information/test.md

Start / Stop local-preview server

Do you want to preview your article? You can start a local-preview server using following command. This is at http://localhost:4000/.

The server will reload files automatically if you make new changes. Please reload your browser.

# Run server
$ docker-compose up
 ...
blog_1  | INFO  Start processing
blog_1  | INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

To stop server, press Ctrl+C and docker-compose down.

# Stop server
^CGracefully stopping... (press Ctrl+C again to force)
Stopping example_blog_1 ... done

$ docker-compose down

Publish Blog with GitHub Pages

In this tutorial, we use GitHub Actions to deploy GitHub Pages.

The repository already has a workflow for GitHub Pages (.github/workflows/upload-gh-pages.yml).

You can achieve publishing your blog easily with following steps.

Commit your changes and Create Pull Request

# Commit changes
$ git add .
$ git commit -m 'Add article'
# Push 'add_article' branch to remote repository
$ git push origin add_article
  ...
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote:
remote: Create a pull request for 'add_article' on GitHub by visiting:
remote:      https://github.com/${ORG_NAME}/blog/pull/new/add_article
remote:
To github.com:${ORG_NAME}/blog.git
 * [new branch]      add_article -> add_article

You can open new Pull Request from https://github.com/${ORG_NAME}/blog/pull/new/${BRANCH_NAME}.

Merge Pull Request

When new changes is merged to main branch, the workflow jobs will be triggered. The jobs automatically builds blog pages and uploads generated files to gh-pages branch.

You can check workflow runs at Actions section on GitHub. https://github.com/{ORG_NAME}/blog/actions

Configure GitHub Pages

Once the workflow is finished, the generated pages can be found in the gh-pages branch of the repository.

To configure GitHub Pages, navigate Settings > Pages section. Select gh-pages branch as source and click Save.

Now you can access your blog! 🎉 https://${ORG_NAME}.github.io/blog/

It could be takes few minutes. If you got 404 page, please try to access later.

Next steps

In this guide, you created a blog repository and then deployed site to GitHub Pages using GitHub Actions workflow.

For more information about GitHub Actions for CSS Blog, see the cssjpn/blog-gh-actions End-to-End Sample Workflows.