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

Docs/add markdown page #3111

Merged
merged 6 commits into from
Dec 14, 2017
Merged

Conversation

pksjce
Copy link
Contributor

@pksjce pksjce commented Dec 3, 2017

This is just a stripped down reproduction of https://www.gatsbyjs.org/blog/2017-07-19-creating-a-blog-with-gatsby/ with generalised terms and actionable steps. I found that this was the minimum setup I required to get my blog working.
Also in the context is https://www.gatsbyjs.org/blog/2017-11-08-migrate-from-jekyll-to-gatsby/


1. Read files in Gatsby from the filesystem.
2. Understand Markdown syntax. Convert metadata to api and content to html.
3. Create a page template from above Markdown data and style it.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"from" should be "for" to match heading below?

@gatsbybot
Copy link
Collaborator

gatsbybot commented Dec 3, 2017

Deploy preview ready!

Built with commit 9b21069

https://deploy-preview-3111--using-drupal.netlify.com

@gatsbybot
Copy link
Collaborator

gatsbybot commented Dec 3, 2017

Deploy preview ready!

Built with commit 4c5a1c9

https://deploy-preview-3111--gatsbygram.netlify.com

}

export const pageQuery = graphql`
query BlogPostByPath($path: String!) {
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you offer just a little more about who / how the $path variable is getting filled in? I thought it would get set in the context parameter in gatsby-node.js but I don't see it there.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review!
So that's a graphQL thingy which I don't completely understand honestly :(
Regardless, wouldn't the right thing to do be point to graphQL docs or graphQL-Gatsby docs at this stage? It would be awfully irrelavant explaining graphQL query structure here no?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I don't mean explain how graphql variables work, I mean specifically what sets the value for that $path variable. If that's a standard thing that's explained somewhere else, then a pointer would be good. I haven't found a place it's explained, though. I only figured out some of how they work by reading code in the examples (gatsbygram in particular).

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I really want to say thank you for writing this, it's already helped me a lot.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry for the delay. I really am only trying this out on the weekend. Thanks for the encouragement. Will finish this up soon.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tamouse - I tried figuring this out. I think I have an idea that possibly some Gatsby Node-api magic is involved, but can't say for sure. Would really love somebody's help on this. Maybe @KyleAMathews can help me with this part of the documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor

@shannonbux shannonbux left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi pksjce! Thanks for submitting this PR! We're excited! I'm helping Kyle Mathews out with docs and will probably be making a few reviews of this file (usually it will be edits for grammar and style rather than actual coding knowledge--so please correct me if I'm wrong!).

This is a stub. Help our community expand it.
Gatsby can easily convert Markdown pages to static pages in your site.
It provides plugins to read and understand folders with markdown files and
node api, which help you create static pages automatically.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My initial feedback is to make sure you write API with all caps. And are you referring to Node.js API? Because if so, then Node.js is capitalized too.

Here's how you do it step by step.

1. Read files in Gatsby from the filesystem.
2. Understand Markdown syntax. Convert metadata to api and content to html.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe HTML is also in all caps.


#### Note on creating markdown files.

When you create a Markdown file, you can add a block that looks like below to the top of the file content. This block will be parsed by `gatsby-transformer-remark` as `frontmatter`. The GraphQL api will provide this data in our React components.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"that looks like the block below"


Gatsby exposes a powerful Node API, which allows for functionality such as creating dynamic pages. This API is exposed in the `gatsby-node.js` file in the root directory of your project, at the same level as `gatsby-config.js`. Each export found in this file will be parsed by Gatsby, as detailed in its [Node API specification](https://www.gatsbyjs.org/docs/node-apis/). However, we only care about one particular API in this instance, `createPages`.

Gatsby calls the `createPages` api (if present) at build time with injected parameters, `boundActionCreators` and `graphql`. Use the `graphql` to query Markdown file data as below. Next use `createPage` action creator to create a page for each of the Markdown files using the `blogTemplate.js` we created in the previous step.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"to query Markdown file data as shown below"

```

Two things are important in the file above.
1. A GraphQL query is made in the second half of the file to get the markdown data. Gatsby has automagically given you all the Markdown metadata and html in this query's result.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe Markdown is always capitalized as well.

Now open up your `gatsby-config.js` to add this plugin to the plugin list.

The plugin list accepts either a string which is the plugin name or an object with any options you may want to pass.
Here we add an object with the path as an option to the plugin
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line is missing punctuation, like a period or colon at the end.

@pksjce
Copy link
Contributor Author

pksjce commented Dec 9, 2017

Hey @shannonbux - I've made the grammatical corrections!

@ghost ghost assigned KyleAMathews Dec 14, 2017
@ghost ghost added the review label Dec 14, 2017
@KyleAMathews KyleAMathews merged commit 616a745 into gatsbyjs:master Dec 14, 2017
@ghost ghost removed the review label Dec 14, 2017
@KyleAMathews
Copy link
Contributor

Thanks @pksjce and the reviewers!

@pksjce
Copy link
Contributor Author

pksjce commented Dec 14, 2017

Yay! Thanks!

@pksjce pksjce deleted the docs/add-markdown-page branch December 14, 2017 00:49
@pksjce
Copy link
Contributor Author

pksjce commented Dec 14, 2017

Hey @KyleAMathews - How would I fix the indentation here?
screen shot 2017-12-14 at 11 52 51 am

@KyleAMathews
Copy link
Contributor

Fixed it in another PR actually :-) it's in the docs-links.yaml file for future reference

@pksjce
Copy link
Contributor Author

pksjce commented Dec 14, 2017

Cool! In my next PR will remember to do that too.

@shannonbux
Copy link
Contributor

shannonbux commented Dec 20, 2017

@pksjce and @tamouse I just wanted to say thank you again for doing the work to fill out this stub article and edit it! You are some of the first brave people to contribute to the new stub articles and it made the process so much faster. Awesome 💃 😸 🙌 and looking forward to your future PR's! :D

@jlengstorf
Copy link
Contributor

Hiya @pksjce! 👋

This is definitely late, but on behalf of the entire Gatsby community, I wanted to say thank you for being here.

Gatsby is built by awesome people like you. Let us say “thanks” in two ways:

  1. We’d like to send you some Gatsby swag. As a token of our appreciation, you can go to the Gatsby Swag Store and log in with your GitHub account to get a coupon code good for one free piece of swag. (We’ve got t-shirts and hats, plus some socks that are really razzing our berries right now.)
  2. If you’re not already part of it, we just invited you to join the Gatsby organization on GitHub. This will add you to our team of maintainers. You’ll receive an email shortly asking you to confirm. By joining the team, you’ll be able to label issues, review pull requests, and merge approved pull requests.

If you have questions, please don’t hesitate to reach out to us: tweet at @gatsbyjs and we’ll come a-runnin’.

Thanks again! 💪💜

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants