|
| 1 | +# 🏗️ Boilerplate for Nuxt, Tailwind & Static CMS |
| 2 | + |
| 3 | +**[Live Demo](https://static-cms-nuxt.netlify.app/)** |
| 4 | + |
| 5 | +An opinionated starter template for a quick start with the following technologies up on a site after only 5 minutes! |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +## 🔋 Batteries included |
| 10 | + |
| 11 | +- Nuxt.js (in "universal mode", where both SEO and speed is great) |
| 12 | +- Vue 2 |
| 13 | +- Vuex (supported by adding to `/store`, but not implemented) |
| 14 | +- PostCSS (no SCSS) |
| 15 | +- Tailwind |
| 16 | +- PurgeCSS (removes unused CSS-selectors) |
| 17 | +- Dark mode & ColorModePicker (Set to "dark mode first") |
| 18 | +- PWA (install website as standalone app) |
| 19 | +- Netlify CMS (no need for a separate server) |
| 20 | +- Prettier |
| 21 | +- Nuxt-content (w/ exensible support for markdown and code-blocks) |
| 22 | + |
| 23 | +##### Optional extra setup |
| 24 | +- Git LFS (store uploaded images outside the main repo) |
| 25 | +- Netlify LM (Netlify’s Git LFS support) |
| 26 | + |
| 27 | +## 🎉 Getting Started |
| 28 | + |
| 29 | +Use the deploy button to get your own copy of the repository. |
| 30 | + |
| 31 | +[](https://app.netlify.com/start/deploy?repository=https://github.com/StaticJsCMS/static-cms-nuxt-netlify-template&stack=cms) |
| 32 | + |
| 33 | +This will setup everything needed for running the CMS: |
| 34 | + - A new repository in your GitHub account with the code |
| 35 | + - Full Continuous Deployment to Netlify's global CDN network |
| 36 | + - Control users and access with Netlify Identity |
| 37 | + - Manage content with Netlify CMS and Nuxt-content |
| 38 | + |
| 39 | +Once the initial build finishes, you can invite yourself as a user. Go to the Identity tab in your new site, click "Invite" and send yourself an invite. Start with by registering a regular email-account (not OAuth yet!) with a [generated password](https://passwordwolf.com/). |
| 40 | + |
| 41 | +You should be up and running, ready for personalization! |
| 42 | + |
| 43 | +### These extra steps are only necessary if you want to upload large media in Netlify CMS: |
| 44 | +This way it doesn't clutter up your repo with large unmanageable files. But *do know* that it is easier to add later than undoing it later. |
| 45 | + |
| 46 | +1. **[Install git-lfs](https://git-lfs.github.com/)** on your computer and remove the `#` in the project's `.gitattributes` |
| 47 | + |
| 48 | +2. **Setup Netlify LM** by following [these steps](https://docs.netlify.com/large-media/setup/). (In short: `netlify plugins:install netlify-lm-plugin` → `netlify lm:install` → `netlify login` → `netlify link` → `netlify lm:setup` → commit the `.lfsconfig` file.) |
| 49 | + |
| 50 | +--- |
| 51 | + |
| 52 | +## Project commands |
| 53 | + |
| 54 | +1. 📦 Install dependencies. |
| 55 | + |
| 56 | +```bash |
| 57 | +npm install |
| 58 | +``` |
| 59 | + |
| 60 | +2. 🏗 Run the project for local dev. This will start a hot-reloading server at `localhost:3000`. |
| 61 | + |
| 62 | +```bash |
| 63 | +npm run dev |
| 64 | +``` |
| 65 | + |
| 66 | +3. 🌌 Build the app for server-side rendered deployment. See more about **Universal SSR** in the [Nuxt.js docs](https://nuxtjs.org/guide#server-rendered-universal-ssr-). |
| 67 | + |
| 68 | +```bash |
| 69 | +npm run build |
| 70 | + |
| 71 | +# And to serve that deployment... |
| 72 | +npm run start |
| 73 | +``` |
| 74 | + |
| 75 | +4. ⚡️ Generate a fully pre-rendered static site. See more [in the docs](https://nuxtjs.org/guide#static-generated-pre-rendering-). |
| 76 | + |
| 77 | +```bash |
| 78 | +npm run generate |
| 79 | +``` |
| 80 | + |
| 81 | +### Personalize setup |
| 82 | + |
| 83 | +1. Copy and change the .env-file |
| 84 | + |
| 85 | + - `cp .env-example .env` |
| 86 | + - Then change the values |
| 87 | + |
| 88 | +2. Change the value on these lines |
| 89 | + |
| 90 | + - `static/admin/config.yml` — `site_url` & `logo_url` |
| 91 | + - `content/site/info.json` — `sitename`, `sitedescription` & `sitelang` |
| 92 | + - `package.json` — `name`, `description`, `author` & `repository.url` |
| 93 | + - `pages/index.vue` — The start page of your new website! |
| 94 | + |
| 95 | +3. Change colors, favicon, content & content collections |
| 96 | + |
| 97 | + - Colors are managed in `assets/scss/_vars.scss` & `tailwind.config.js` |
| 98 | + - Favicon is generated by [@nuxt/pwa](https://pwa.nuxtjs.org/). You should change the `static/icon.png` to something new, and then match the new filename and source in `nuxt.config.js` under `pwa.icon`. Replace the preview.jpg as well. |
| 99 | + - Content is managed mainly in [local Netlify CMS](http://localhost:3000/admin) by going to your `/admin`, in development mode by double-clicking on a post or by hand in `/content` |
| 100 | + - Content collections are managed in `static/admin/config.yml` |
| 101 | + |
| 102 | +4. Change font |
| 103 | + |
| 104 | + 1. Add/change your font link in `nuxt.config.js` under `head.link`. You can add a `<link rel="stylesheet" href="font.css">` as `link: [{ rel: 'stylesheet', href: 'font.css' }]`, like [this](https://vue-meta.nuxtjs.org/api/#link) |
| 105 | + 2. Then append your font name in `tailwind.config.js` under `theme.extend.fontFamily.sans` (or other). |
| 106 | + 3. Then if you've uncommented the included netlify plugin "[Subfont](https://github.com/Munter/netlify-plugin-subfont#readme)" in `netlify.toml`, it will automatically post-processes your web page to use an optimal font loading strategy. |
| 107 | + |
| 108 | +## More info |
| 109 | + |
| 110 | +> This project was bootstrapped with `create-nuxt-app`. There are more detailed explanations of how everything works in the [Nuxt.js docs](https://nuxtjs.org). |
| 111 | +
|
| 112 | +### Netlify Identity |
| 113 | + |
| 114 | +Make sure to set to "registration invite only" [here](https://app.netlify.com/sites/YOUR_NETLIFY_SITE_SLUG/settings/identity#registration-preferences) if you don't want spam. |
| 115 | + |
| 116 | +When you create your first account, _don’t_ sign up using OAuth, generate a new password and sign in that way locally, otherwise a successful login will send you to the URL you typed in instead of keeping you on localhost. |
| 117 | + |
| 118 | +If you want the Netlify signup emails to work with this boilerplate, you need to either add the 'netlify-identity-widget' to `nuxt.config.js` under `head`, [Follow the advice here](https://answers.netlify.com/t/common-issue-netlify-cms-git-gateway-email-not-confirmed/10690). Or enable the fixed and included email-templates’ paths in Netlify, under [Site Settings > Identity > Emails](https://app.netlify.com/sites/YOUR_NETLIFY_SITE_SLUG/settings/identity) and there you can set `/static/emails/THE_TEMPLATE_NAME.html` for each template. |
| 119 | + |
| 120 | +--- |
| 121 | + |
| 122 | +Originally based on [Henry Desroches' nuxt-netlify-cms-starter](https://github.com/xdesro/nuxt-netlify-cms-starter). |
| 123 | + |
| 124 | +--- |
| 125 | + |
| 126 | +## Troubleshooting |
| 127 | + |
| 128 | +- > I added a CSS class, but it doesn't show |
| 129 | +- It is most likely purged by PurgeCSS, make sure it is whitelisted in `purgeCSS` in `nuxt.config.js` |
| 130 | + |
| 131 | +- > I can’t log in to `/admin` on localhost and use my local git as CMS |
| 132 | +- Open up a new terminal and run `npx static-cms-proxy-server`, the login again. |
| 133 | + |
| 134 | +- > I tried logging into/saving in Netlify CMS, but I can't |
| 135 | +- It may be that you haven't [enabled Netlify Identity](https://app.netlify.com/sites/YOUR_NETLIFY_SITE_SLUG/settings/identity) or [setup the Git Gateway](https://app.netlify.com/sites/YOUR_NETLIFY_SITE_SLUG/settings/identity#services) correctly, [check the docs](https://staticjscms.netlify.app/docs/git-gateway-backend/) |
| 136 | + |
| 137 | +- > I get Netlify emails but can't use them to login etc. |
| 138 | +- It is probably because the 'netlify-identity-widget' is only included in the `/admin`-page. [Follow the advice here](https://answers.netlify.com/t/common-issue-netlify-cms-git-gateway-email-not-confirmed/10690) or enable the included email-templates’ paths in Netlify, under [Site Settings > Identity > Emails](https://app.netlify.com/sites/YOUR_NETLIFY_SITE_SLUG/settings/identity) and there you can set `/static/emails/THE_TEMPLATE_NAME.html` for each template. This will make sure to use the correct links inside the emails. Look at @audetcameron’s [screenshot here](https://github.com/StaticJsCMS/static-cms-nuxt-netlify-template/issues/8#issuecomment-841469850). |
| 139 | + |
| 140 | +- > "This repository is configured for Git LFS but 'git-lfs' was not found on your path." |
| 141 | +- Install git-lfs then run `git lfs install` in project root. Then to download the images, run `git lfs pull`. Or if you don't want to download the files/can't login to the lfs server, run `git lfs install --skip-smudge` instead. |
| 142 | + |
| 143 | +- > I can’t get Git LFS to run correctly on Netlify |
| 144 | +- Make sure that you have in your [Netlify build settings](https://app.netlify.com/sites/YOUR_NETLIFY_SITE_SLUG/settings/deploys#environment-variables), set the environment variable `GIT_LFS_ENABLED` : `true`. Then also make sure that Netlify LM is setup as [their docs](https://docs.netlify.com/large-media/setup/) specify. |
0 commit comments