You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 25, 2021. It is now read-only.
This section describes steps for direct contribution to this template.
8
+
9
+
1. Checkout git repository.
10
+
2. Install dependencies.
11
+
```sh
12
+
$ npm install
13
+
```
14
+
3. Automatically install and build the template to a test folder.
15
+
```sh
16
+
$ npm run test
17
+
```
18
+
19
+
Now, whenever you make changes to the source files in `template/`, you can directly test the installation
20
+
and the build. It isn't possible to directly build the project inside `template/` due to variables
21
+
that get replaced during the vue init steps.
22
+
23
+
## Commit Message Guidelines
24
+
25
+
### Commit Message Format
26
+
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
27
+
format that includes a **type**, a **scope** and a **subject**:
28
+
29
+
```
30
+
<type>(<scope>): <subject>
31
+
<BLANK LINE>
32
+
<body>
33
+
<BLANK LINE>
34
+
<footer>
35
+
```
36
+
37
+
The **header** is mandatory and the **scope** of the header is optional.
38
+
The **footer** can contain a ticket reference in case the commits don't get squashed.
39
+
40
+
The body should contain a user friendly description of the change. most likely, the header contains the "What was changed" while the body explains the "Why". See the body as the part that goes to a end-user changelog.
41
+
42
+
```
43
+
docs(changelog): update changelog
44
+
```
45
+
```
46
+
fix(layouts): add additional horizontal space
47
+
48
+
The layout was improved to look better on big viewports.
> Build server-less, static websites with Vue.js and Netlify CMS.
4
8
5
-
This is a fork of the [Nuxt.js starter project](https://github.com/nuxt-community/starter-template) with the goal, to extend it with [Netlify CMS](https://www.netlifycms.org) for building pre-rendered, server-less websites. See the [Further explanation](#further-explanation) section for more information.
9
+
This is a starter template to build static websites with Vue.js and Netlify CMS, based on Nuxt v1.x. What it covers:
10
+
11
+
***Setup via Vue CLI** 🏗
12
+
Easily setup a nearly blank Nuxt.js project.
13
+
*Currently not optimized for Vue CLI v3.0*.
14
+
***Content editing via Netlify CMS** ✏️
15
+
Netlify CMS is a client-side CMS connecting directly to your git repository to edit markdown files.
16
+
*Also supports other file formats, but this template only works with the default, frontmatter markdown format.*
17
+
***Show content in Vue.js via Nuxtent/Nuxtdown module** 🔍️
18
+
The Nuxtdown module (fixed fork from Nuxtent) allows querying the content and show in the UI.
19
+
***Static-site generation via Nuxt.js** ✅
20
+
Nuxt.js, the famous framework to build universal Vue.js applications, generates a static-site.
Out of the box, the UI doesn't have a clue where your content is stored and which dynamic routes belong to which content. Nuxt.js can only map static pages by default. Dynamic routes like blog posts with different file names are not detected. The configuration for this happens by Nuxtdown.
General information like HTML `<head>` tags and page titles are set via Nuxt.js. Don't bother with routing configuration for Nuxt.js, this is solved by Nuxtdown.
During development, run the client-side SPA version of your application. Use the `dev` or `serve` task, whatever fits you better. They do the same.
79
+
40
80
```bash
41
81
# serve with hot reloading at localhost:3000
42
82
$ npm run dev
@@ -46,124 +86,20 @@ Go to [http://localhost:3000](http://localhost:3000)
46
86
47
87
### Production
48
88
89
+
For production, generate the static-site.
90
+
49
91
```bash
50
92
# generate a static project
51
93
$ npm run generate
52
94
```
53
95
54
96
While the other commands from Nuxt.js remain in this starter kit, we clearly focus on serving static HTML files, thus the `generate` command is our task to create the website for production.
55
97
56
-
## Further explanation
57
-
58
-
The goal of this boilerplate is to allow creating websites server-less and enable content management
59
-
with a CMS at the same time. It's all about saving time, saving money and especially keep to front-end work, while allowing people to edit content.
60
-
61
-
### What it does
62
-
63
-
*[x]**Pre-rendering:** Uses Nuxt.js to pre-render your Vuejs website to static HTML files.
64
-
*[x]**Easy dynamic route rendering**: Allows to map glob patterns to your Nuxt.js page paths.
65
-
This (partially) removes the need to define all dynamic routes by hand.
66
-
*[ ]**Automatic mapping dynamic routes for pre-render:**: No more need to define dynamic routes manually.
67
-
Netlify CMS and Nuxt.js sync their routes automatically.
68
-
*[x]**CMS:** Allows to edit content without the need of a server, thanks to Netlify CMS.
69
-
70
-
### How it works
71
-
72
-
For this particular example we use following libraries and frameworks:
73
-
74
-
***Vue.js with Nuxt.js**: Vue.js for building our application and Nuxt.js for pre-rendering it.
75
-
In general, this could be anything here as long it can read json or markdown files and is can be
76
-
pre-rendered.
77
-
***Netlify CMS**: A CMS which is built on JavaScript and connects to the Git repository.
78
-
It defines the content models and edits the content files in the repository.
79
-
80
-
Basically, we use the default Nuxt.js boilerplate, add Netlify CMS files and extend the Nuxt.js config
81
-
to collect all content files and add those routes automatically to your Nuxt.js files.
82
-
83
-
Nuxt.js doesn't pre-render dynamic routes, e.g. blog/post/my-blog-post-2. But it allows to add the urls to those
84
-
pages manually to your config. Since you don't want to add a route to your config everytime you publish a blog post,
85
-
we allow to set dynamic paths with a glob in the Nuxt.js config. Those define glob folders are grabbed and
86
-
all files are added as routes to the Nuxt.js generate.route config_.
87
-
88
-
#### Principles
89
-
90
-
A pragmatic overview what this does.
91
-
92
-
1. You have a plain Vue.js and Nuxt.js website. That's fine and it works, but you want your pages to
93
-
be SEO optimized. So you have two choices: Getting a node server for rendering your website server-side or
94
-
you use pre-rendering, which converts all your pages to static HTML pages. This boilerplate does the second one.
95
-
2. You add Netlify CMS and connect it to your repository. Now you can create content as json that is stored in
96
-
a content folder in your repository.
97
-
3. Through webpack, you import the content into your pages and show it to the users.
98
-
4. In addition, you run Nuxt.js' generate command to make all this rendered as static HTML files.
99
-
5. Everytime a file changes in the repository, the generate command has to be run so the static files of the
100
-
website are up to date. _This is not part of this boilerplate. I assume you know how this works with your
101
-
favourite CI.
102
-
103
-
### Why?
104
-
105
-
Tired of the time investment needed to setup a website that needs to be progressive enhanced,
106
-
SEO friendly, accessible and allows to access all content on client-side to benefit from doing additional
107
-
UX improvements like page transitions, this is an attempt to make the process for building small or medium sizes
108
-
CMS websites fast, easy to edit and easy to use.
109
-
110
-
You can do all this with CMS like WordPress if you're willing to invest your time:
111
-
You have to get an Apache server with PHP, setup WordPress, somehow setup the custom post types
112
-
and custom fields (probably by installing ACF), setup the WordPress JSON API, write your templates
113
-
in PHP + probably even a second time so you can render them with client-side technology. And then,
114
-
at the end, having a website that maybe changes once in a couple of weeks.
115
-
116
-
This looks like a lot of work for sharing content with the internet.
117
-
118
-
Second, plain old HTML is still the best. The technology stack in this boilerplate exactly
119
-
does that, but gives you the additional tools for content editing and for building advanced web experiences.
120
-
121
-
In the end, you don't need Vue.js or Nuxt.js. You can get rid of it. You can pre-render your vanilla JavaScript
122
-
with Webpack, for sure. You don't need Netlify CMS. Authors could edit Markdown and JSON files directly in the repository.
123
-
BUT this is not what we want. We don't want people to get to know Git, we don't want them to edit JSON or Markdown files
124
-
without validate their entries.
125
-
126
-
### Uncertain
127
-
128
-
#### Build performance with a big amount of pages (e.g. 20'000)
129
-
130
-
While I've read a while ago that the Nuxt.js documentation is built pre-rendered with up to 20'000 pages.
131
-
It's not clear at this point how long such a build takes and how a partial build process could look like.
132
-
133
-
#### Building different sizes of images
134
-
135
-
This certainly is an easy one since you could check folders of images and could create a task in webpack or your
136
-
CI system to create additional image sizes. Also here, this would have to be a task that partially resizes images
137
-
only if they changed.
138
-
139
-
#### No error check for missing globs
140
-
141
-
The build might fail all over if you map routes to content that doesn't exist. This will be easy to fix.
142
-
143
-
### When not to use a static server-less system like this
144
-
145
-
When your website changes a lot. For example, if you're building news websites whose content changes all 5 minutes,
146
-
this would mean, that the whole website is re-generated all 5 minutes. Certainly not the best idea. In this case
147
-
you might be better with something more dynamic. But the good part is: If you're building your website on a framework like
148
-
Nuxt.js, you can simply switch to server-rendering as soon
149
-
as the static, server-less behaviour does not longer fit
150
-
your needs. It's as easy as switching two commands in your
151
-
build system (and probably changing those window instances that don't work server-side).
152
-
153
-
## Development
154
-
155
-
This section describes steps for direct contribution to this template.
98
+
## Contribution
156
99
157
-
1. Checkout git repository.
158
-
2. Install dependencies.
159
-
```sh
160
-
$ npm install
161
-
```
162
-
3. Automatically install and build the template to a test folder.
163
-
```sh
164
-
$ npm run test
165
-
```
100
+
If you're interested in contributing to the project, see [CONTRIBUTING.md][contributing]
166
101
167
-
Now, whenever you make changes to the source files in `template/`, you can directly test the installation
168
-
and the build. It isn't possible to directly build the project inside `template/` due to variables
0 commit comments