Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Guide] Using Netlify CMS with Jekyll #2248

Merged
merged 9 commits into from Apr 5, 2019

Conversation

Projects
None yet
2 participants
@adamwatters
Copy link
Contributor

commented Mar 26, 2019

Summary
Jekyll guide for #2092

Hasn't been proofread yet, but should be ready if anyone wants to walk through it and give general feedback.

@netlify

This comment has been minimized.

Copy link

commented Mar 26, 2019

Preview proposed changes to the CMS demo site in the link below:

Built with commit 203ecfb

https://deploy-preview-2248--cms-demo.netlify.com

@adamwatters adamwatters referenced this pull request Mar 26, 2019

Open

We need guides. #2092

4 of 16 tasks complete
@erquhart

This comment has been minimized.

Copy link
Member

commented Mar 28, 2019

Man, this is one serious guide @adamwatters!! Will get a review up soon!

@netlify

This comment has been minimized.

Copy link

commented Mar 28, 2019

Preview proposed changes to netlifycms.org in the link below:

Built with commit 203ecfb

https://deploy-preview-2248--netlify-cms-www.netlify.com

@adamwatters

This comment has been minimized.

Copy link
Contributor Author

commented Mar 28, 2019

Man, this is one serious guide @adamwatters!! Will get a review up soon!

@erquhart lol I know - it might be too much? I think I can pare it back some when I revise tomorrow.

@erquhart

This comment has been minimized.

Copy link
Member

commented Mar 29, 2019

Probably could do some trimming, but definitely great stuff. Here's a direct link to your deploy preview, it'll update if you push more commits:

https://deploy-preview-2248--netlify-cms-www.netlify.com/docs/jekyll/

@adamwatters

This comment has been minimized.

Copy link
Contributor Author

commented Apr 2, 2019

@erquhart - ok - I think I'm done!

I didn't see a simple way to reference the static/img from my markdown, so the embedded images are still broken.

Also, for some reason I'm not seeing my updates at https://deploy-preview-2248--netlify-cms-www.netlify.com/docs/jekyll/

@erquhart

This comment has been minimized.

Copy link
Member

commented Apr 2, 2019

We're currently using absolute urls for images, eg. https://www.netlifycms.org/img/email-subject.png?raw=true. Include the raw=true query. The preview of your changes on the PR doesn't currently auto-update, happens later.

@erquhart
Copy link
Member

left a comment

I went ahead and reviewed about half of the PR with specific notes. Before removing all of the sections that I mention in my review, I would recommend maybe taking this entire entry and publishing it on your blog if you have one? It's a great in-depth tutorial, but needs to be shaved down for our purposes here. If you can get a feel for the kind of changes expected here and take a second look at the rest of the PR you may find more sections that are out of scope and ripe for trimming or removal.

Thanks again for all of your time on this, it's going to be a great resource!


You have lots of options for hosting and serving your project, but to for the sake of simplicity this guide will assume you [follow this guide](https://www.netlify.com/blog/2015/10/28/a-step-by-step-guide-jekyll-3.0-on-netlify/) to create a remote git repository on Github and give Netlify access to build and serve the project when you push changes.

### Why Not Stop Here?

This comment has been minimized.

Copy link
@erquhart

erquhart Apr 2, 2019

Member

This section is a little out of scope, can probably be dropped.

This comment has been minimized.

Copy link
@adamwatters

adamwatters Apr 4, 2019

Author Contributor

Done 👍

cd admin && touch index.html
```

Copy the following HTML into `index.html`.

This comment has been minimized.

Copy link
@erquhart

erquhart Apr 2, 2019

Member

We want to avoid a lot of remedial instruction in this guide. General familiarity with creating files and using Jekyll should be assumed, and other learning resources can be linked where necessary, as you've done above.

Everything from the "Add admin/index.html" section header to this line can be condensed to a single sentence, Eg.:

Create a file admin/index.html in the repo of your root - it should look like this:

This comment has been minimized.

Copy link
@adamwatters

adamwatters Apr 4, 2019

Author Contributor

Done 👍

- `folder` should be set to the directory containing the files we want the cms to be able to create and edit. We'll start with `"_posts/"`
- The `fields` property requires an array of field objects. We'll start with a collection with only the property `name` defined. Setting the `fields` property will take care of the `files` property error as well.

With these update, `config.yml` should look like this.

This comment has been minimized.

Copy link
@erquhart

erquhart Apr 2, 2019

Member

We should drop all of the config warning steps and just give them a working config using the test-repo backend up front. The walkthrough of configuration requirements may be helpful for some, but it's out of scope for this guide, which should focus entirely on the intersection of Jekyll and Netlify CMS.

We could delete everything between this line and the index.html code block above, and rework this line a bit to fit that context.

This comment has been minimized.

Copy link
@adamwatters

adamwatters Apr 4, 2019

Author Contributor

I removed setting backend to test-repo entirely because it seemed like an unnecessary intermediary step when the next section is links to the docs for setting up Identity/Git-gateway and adding the Identity widget

});
}
</script>
```

This comment has been minimized.

Copy link
@erquhart

erquhart Apr 2, 2019

Member

The detailed walkthrough of setting up identity should be replaced with a link to the git-gateway page in these docs - otherwise if the details of how this works changes, we have multiple places to update, and likely won't catch them all. Better to have a single source of truth and just link there.

adamwatters added some commits Apr 4, 2019

removed identity/gitgateway, remedial steps, all screenshots except t…
…he one showing what the tutorial blog looks like
@adamwatters

This comment has been minimized.

Copy link
Contributor Author

commented Apr 4, 2019

If you can get a feel for the kind of changes expected here and take a second look at the rest of the PR you may find more sections that are out of scope and ripe for trimming or removal.

Removed all the remedial / redundant step-by-step stuff you called out in your feedback 👍 I mostly left the configuration for the Blog, Authors, About Page, and Navigation alone.

@adamwatters adamwatters closed this Apr 4, 2019

@adamwatters adamwatters reopened this Apr 4, 2019

@erquhart

This comment has been minimized.

Copy link
Member

commented Apr 5, 2019

Looks great, I think it's good to merge!! Thanks @adamwatters 🎉 🎉

@erquhart erquhart merged commit 9b1dfe1 into netlify:master Apr 5, 2019

2 checks passed

netlify.netlify-cms Build #20190404.10 succeeded
Details
netlify/cms-demo/deploy-preview Deploy preview ready!
Details
@adamwatters

This comment has been minimized.

Copy link
Contributor Author

commented Apr 5, 2019

Awesome! Thanks for reviewing and merging @erquhart

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.