README.md

✍️

Handmade Blog

Handmade Blog is a classic static blog generator for people who want to start a blog quickly. It supports article type document for a blog post, work type document for portfolio, code highlights, KaTeX syntax, footnotes, and more.

Demo: Here

Getting Started

1. Click the 'Use this template' button above the file list to create a new repository. If you want to use github.io domain, have to name the repository {YOUR_ID}.github.io. (e.g., betty-grof.github.io) Don't forget to enable the 'Include all branches' option.

   

   

2. Click the 'Settings' tab in your repository, and set the source branch for GitHub Pages to gh-pages branch. GitHub Pages will host your website based on gh-pages branch. You'll be able to access the website via https://{YOUR_ID}.github.io/ in a few minutes.

   

   

3. Clone the repository, and install node packages.

   $ git clone https://github.com/{YOUR_ID}/{REPOSITORY_NAME}.git # git clone https://github.com/betty-grof/betty-grof.github.io.git
   $ cd {REPOSITORY_NAME} # cd betty-grof.github.io
   $ npm install

4. Modify config.json file in services directory to set your blog title and subtitle.

   {
     "blogTitle": "Betty Grof",
     "blogSubtitle": "Oh My Glob",
     "article": {
       "tableOfContents": true 
     }
   }

5. Start a local server at http://localhost:1234/. npm start script opens the local server based on server directory.

   $ npm start

   

6. Commit and push the changes in your working directory to the remote repository.

   $ git add ./services/config.json
   $ git commit -m "Set the blog title and subtitle"
   $ git push origin master

7. Run deploy script if you're ready to host a live server. This script builds local files to dist directory and pushes it to gh-pages branch that contains only the files in dist directory. GitHub Pages will host live server at https://{YOUR_ID}.github.io/ based on gh-pages branch automatically.

   $ npm run deploy

Usage

Write and publish a document

1. Write a document in _articles or _works directory.

2. Run npm run publish article or npm run publish work script to convert markdown documents to HTML.

3. Preview converted document on the local server using npm start script.

4. Commit and push the changes to the repository, and run npm run deploy to publish the document to live server.

Change a page

Modify an ejs template to change the contents of the existing page. For example, if you want to put an image to the landing page, open the app/templates/index.ejs file, and add img tag to the main-container element.

<main id="main-container">
  <img src="../assets/profile.jpg" alt="My profile picture" />
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
</main>

Then, run npm run publish page script to publish the modified landing page.

$ npm run publish page

Done! You can change not only the landing page but any pages like this way. (You may need to understand the project structure.)

Project structure

• _articles - Markdown files for the blog posts.
• _works - Markdown files for the portfolio.
• app
  • assets - Any files to be imported by HTML files such as image, font, etc.
  • public - HTML files generated by publish script. server and dist directory is based on this directory. Do not change the files under this directory directly.
    • article - HTML files converted from _articles directory.
    • work - HTML files converted from _works directory.
  • src - Source code to be imported by HTML files.
    • css - CSS files generated by build script.
    • scss
    • ts
  • static - Any static files that aren't compiled by build script like robots.txt, sitemap.xml, or SEO files. build script copies all files under this directory to dist directory.
  • templates - HTML files used as ejs template. publish script converts a markdown file to HTML based on templates under this directory.
• dist - Files compiled by build script. deploy script deploys a website to GitHub pages based on this directory. Do not change the files under this directory directly.
• server - Files compiled by build script. start script opens local server based on this directory. Do not change the files under this directory directly.
• services - Source code implementing publish script.
  • classes
  • models
• tools - Source code implementing various npm scripts.

Showcase

• parksb.github.io: https://github.com/parksb/parksb.github.io

Available Scripts

npm start

Starts local development server at http://localhost:1234/.

npm run publish

Converts templates to HTML files.

$ npm run publish article

Converts all articles.

$ npm run publish works

Converts all works.

$ npm run publish article 5

Converts an article which id is 5.

$ npm run publish work 3

Converts a work which id is 3.

$ npm run publish page

Converts all pages.

npm run watch

Rebuilds template files in templates directory and markdown files in _articles directory automatically whenever the files are modified.

npm run build

Builds files with parcel bundler.

npm run deploy

Builds and deploys the files.

License

This project is licensed under the MIT License - see the LICENSE file for details.