Get Start
This tutorial will show your how to setup a project with BlogiNote step-by-step.
Let's Go
Setup Environment
Optional Step
The steps in this part is optional.
If you just need to write the markdown files locally (then upload to the remote repository at Github), you can skip this section.
If you wants to test or preview the web pages generated from markdown files locally, you should follow these steps.
- Install the Node.js first:
you can download the latest LTS Version Node.js installer from the Node.js Homepage (please select the suitable installer for your computer system) and install it.Recommend
A better way for developer to install the Node.js is using nvm.
nvm can manage multiple Node.js versions and change the active version easily.
nvm is just for UNIX, Mac and Windows WSL. You can try the nvm-windows for Windows.
- Then run the follow command at terminal to install the
yarn
package globally:bashnpm i yarn
- Install Git:
Git is a free and open source version control system, we will use it to control the version of blog posts content, and sync the content between local project and remove repository at Github.Version Control
Version Control is a software engineering concept.
In the lifetime of a software, the code will change many times.
After added new features or fixed bugs, developers will release the new version to mark the changes.
- Install Visual Studio Code:
Visual Studio Code is an open source editor, it provide many useful features and plugins for developer.Tip
If you just want to write some markdown files (as blog posts), and don't need to code for adding the custom features, you can install any Markdown Editor as you like.
β¨ If you don't want to install any extra editor on your local PC, you can try this StackBlitz project.
This is an free online coding environment running the BlogiNote, it works right out of box π you create any new markdown files as you want, then the preview window on the right side will update simultaneously.
Register Github and Vercel
- Register a Github account first:
Tip
Github is an online hosting service for code.
The source code of BlogiNote is also hosted by it.
You need to register an account of Github, because the next step is to copy the starter template from it.
the quota of the Github Free Plan is enough for this project. - Then register a Vercel account:
We need to deploy our static website to this platform.
the quota of the Vercel Free/Hobby Plan is fine for this project. If your website need more bandwidth, you can upgrade the plan at any time.Recommend
The more convenient way is to Login Vercel with the Continue with Github option.
Use Starter Template
The most easy way to build your own project is using the starter template of BlogiNote.
Warning
You should have a Github account and login before the next step.
Please check out the previous section Register Github and Vercel Account about how to register a Github account.
Fork Template
Open this website and click the Fork button at the top-right corner of the page.
Then you will create a copy of the repository under your Github account.
Now you have full control over this duplicated repository, for example you can click the Settings tab, and rename your repository in the Repository name
input box.
Download Template
Optional Step
The steps in this part is optional.
If you just need to write the markdown files, then upload to the remote repository at Github, you can skip this section.
If you wants to test or preview the web pages generated from markdown files locally, you should follow these steps.
After fork the template, you can click the Code button at the repository (under your Github account) page.
Then you will see a pop-up menu with some options to Clone/Download the code to your local PC.
- You can use command to download the code:
the pop-up menu first option show multiple tabs, under theHTTPS
tab there is a link, click the button to copy it
then run the command in terminal to download the code (the_link_url
stand for the link you just copy mentioned above β)bashgit clone the_link_url
Warning
Before execute the command in terminal, you should install Git software in your PC first.
Please check out the previous section Setup Environment step 3 for more information.
- Another way is just clicking the Download ZIP option to download a ZIP file, then Unzip it
Run Locally
Optional Step
The steps in this part is optional.
If you just need to write the markdown files, then upload to the remote repository at Github, you can skip this section.
If you wants to test or preview the web pages generated from markdown files locally, you should follow these steps.
Warning
Before you follow the steps in this section, you should install VS Code in your PC first, because all the steps will running inside this software.
Please check out the previous section Setup Environment step 4 for more information.
Open the folder you download (from the previous step) with VS Code.
Because this is a project based on Nuxt 3, so you should follow the Nuxt documentation to setup the VS Code environment first:
- Install the VS Code extension Volar
- Enable Take Over Mode:
- make sure Volar update to 0.27.17
- Disable built-in TypeScript extension:
- Press the shortcut
Shift
+Ctrl
+P
to open the Command Palette of VS Code - Run the command
Extensions: Show Built-in Extensions
to open the Extension sidebar menu - Find
TypeScript and JavaScript Language Features
and right click and selectDisable (Workspace)
- Press the shortcut
- Reload VS Code
- Add some code in the
nuxt.config.ts
file to disable generating the shim for*.vue
filesnuxt.config.tstsexport default defineNuxtConfig({ typescript: { shim: false } })
Tip
The BlogiNote support Tailwind CSS to style the page, you can install the relative VS Code extension Tailwind CSS IntelliSense.
Then press the shortcut Ctrl
+ ~
to open the terminal panel, run the command in terminal to install the dependent packages for the project
yarn install
Warning
Before execute the command in terminal, you should install yarn package globally first.
Please check out the previous section Setup Environment step 2 for more information.
After install the dependent packages, run the command in terminal to start a development server locally
yarn dev -o
then a browser window should automatically open for http://localhost:3000
Tip
The terminal will output the local server url >Local: http://localhost:3000
The default port is 3000
, if this port has been used, the server engine will choose another port automatically.
If the browser window doesn't open automatically, you can click the url at terminal by holding the Ctrl
key to open it.
The terminal also output another url Network: http://192.168.0.114:3000/
you can access this url with any devices in the same local area network.
Write Articles
Create any markdown files in the π content/article
folder to write any articles.
Tip
If you want to learn more about how to write an article, please check out another tutorial Write an article
Upload Changes
After you finish writing or editing the articles, you should upload or sync the changes from the your local PC to the remote Github repository.
There're many methods or tools to commit changes, and this tutorial will show you two ways:
- Commit Changes at Github Webpage: it's out of the box, you just need to open the repository page then drag and drop the markdown files to upload.
- Commit Changes by VS Code: VS Code work well with Git and support to commit changes from local PC to the remote Github repository.
Commit Changes at Github
If you don't setup the development environment at your local PC, you can upload the articles (the markdown files) you have wrote to Github at the repository webpage.
Click the Add file button at the repository page, then you will see a pop-up menu with two options Create new file
and Upload files
, choose one option.
Then you will jump to another page:
- If you choose the
Create new file
option
you will get two input box at the page, the smaller input box to set the name of the file (with file extension), and the bigger input box to set the content of the fileCreate New File Tip
You can click the Preview tab to preview the markdown file
- If you choose the
Upload files
option
You will get a upload file box at the page.
You can click this box to open a window, then select the files or the entire folder from your local PC and upload them.
You can also drag and drop the files or entire folder from your PC to the input box to upload them directly.Upload Files
Tip
You should create or upload markdown files inside the π content/article
folder.
So you should navigate into the π content/article
folder first, by clicking the folders step by step π content
-> π article
.
Then click the Add file button to create or upload the files.
If you want to create a new markdown file named test.md
inside a new folder named π tutorial
(which don't exist inside the π content/article/
folder).
First, you should type the tutorial
in the smaller input box first, and enter with the /
slash, then you will see the tutorial
added to the path, then you can type the name of the file test.md
inside the smaller input box and write the content in the bigger input box.
At the bottom of this page, there's a dialog called Commit changes
, you should write a title and description for this action, then click the Commit changes button to upload changes to Github.
Commit Changes by VSCode
If you has setup environment, you can use VS Code to commit changes to the remote Github repository.
VS Code provides a sidebar for you to commit changes to Github repository, it's convenient and you just need to click some buttons.
Warning
If you want to commit change by VS Code, you should install VS Code at your PC first.
Please check out the previous section Setup Environment step 4 for more information.
Tip
You can check out the VS Code documentation for more information about how to using Git.
Deploy to Vercel
Warning
You should have a Vercel account and login before the next step.
Please check out the previous section Register Github and Vercel Account about how to register a Vercel account.
Click the Add New... button at the top-right corner, and choose the Project option in the drop down menu.
You will jump to another page, click the Continue with Github option, then the page will show the Import Git Repository component.
Enter the name of your Github repository at the search input box Search... to search it, and click the Import button of the match repository.
Tip
If the page show the No Results Found warning, you should click the Configure Github App button and configure the Github first, following the steps at Github to allow the Vercel to access the repository.
After import the Github repository to Vercel, you will jump to another page to Configure Project. In this page, you should setup one option. Clicking the Build and Output Settings button to expand it.
In the expanded sub-menu you should switch the button under the Build Command option, then you can write the command yarn generate
inside the input box next to it.
Then all you need to do is clicking the Deploy button under the menu.
The other heavy work will automatically run in the background in Vercel. It will run BlogiNote program to parse the markdown files to web pages first, then deploy them to a server.
All these steps will finish within a minutes (the built time based on your content), and finally you will get a link of the project.
Tip
You can add some custom domains for your project website.
π Just click to visit your website!
Tip
After the first deploy, Vercel platform will monitor your Github repository. When you change the content of the Github repository, Vercel will auto rebuild the website for you.
It means each time you upload the new blog article to the Github repository, you just need to wait a minutes then refresh the browser, you can see the new blog post.
Yep so easy