docs: guide for porting an html site to gatsby #18609

Jeddf · 2019-10-14T12:31:50Z

Description

This PR adds a reference guide for porting part of a HTML website to Gatsby.

For context, and possible further use, I've pushed up the whole example site and finished port to a personal repo.

Possible improvements:

This PR places it in the Porting to Gatsby reference guide overview but it feels closer to a tutorial as it strives to stay focused for an audience that has a very particular task in mind and may only have worked with HTML and CSS. Might be better broken up into tutorials or with some parts replaced by links to recipes?
Remove S3 asset links? (I think they're handy for demonstrating the utility of assetPrefix but probably not suitable for inclusion in the guide)
Create a basic starter with Helmet and a basic Layout component already added so we can skip those parts?

Related Issues

Fixes #13813

Preview (in 2 parts 😂) - updated for `02061cc`

gillkyle

This is really really great content @Jeddf! Thanks so much for working on this and taking on a such a long guide. 🎉

Thanks for making the distinction between guides vs tutorials, this does read like a tutorial in a lot of ways, though I sort of feel like that could be okay in this case given the nature of this content.. 🤔 I'm sure others from @gatsbyjs/learning or Core might chime in with some suggestions.

I gave some ideas for you to consider mostly in linking to additional content and trying to clarify some things.

docs/docs/porting-part-of-a-html-site-to-gatsby.md

gillkyle · 2019-10-15T16:10:50Z

docs/docs/porting-part-of-a-html-site-to-gatsby.md

+export default () => <div>Hello world!</div>
+```
+
+Run the development server in the command line to see the website:


In regards to your comment about this guide resembling a tutorial in some places, perhaps this line is enough, and we could remove the lines below about the gatsby develop command and seeing the site in your browser. Opting to cross reference them in a guide like the Quick Start, so we don't have to duplicate those steps? 🙂

Yeh I agree, I have a strong urge to keep 'em on the page but this is a good spot to remind them about the rest of the docs that they can move onto after too.

docs/docs/porting-part-of-a-html-site-to-gatsby.md

Co-Authored-By: Kyle Gill <kylerobertgill@gmail.com>

Jeddf · 2019-10-15T19:03:53Z

Thanks @gillkyle, appreciate that coming from the CRA port master! ⚓️

Yeh I kept looking at spots to link to in the docs but they didn't quite seem to fit with trying to minimize JavaScript and stick to the basic, static application. Definitely think there might be other approaches though, it's an interesting one.

muescha

My nitpicks ...

docs/docs/porting-part-of-a-html-site-to-gatsby.md

muescha · 2019-10-16T14:06:31Z

I miss in the further steps section:

how I port a second/third folder to Gatsby? There is only one pathPrefix: Do i need a second, third Gatsby for this?
how I port the full site to Gatsby? (By add who folder to the src director, removing pathPrefix ...)

Co-Authored-By: Michael <184316+muescha@users.noreply.github.com>

Jeddf · 2019-10-16T15:59:52Z

Thanks for taking a look @muescha! Those ideas for further steps both sound good, I'll look at adding them in later today 👍.
~~I'm not sure about a neat solution for porting multiple sections, will do a little thinking/reading on that.~~ Ack actually, this'll be pretty straightforward I think, just a case of mirroring the site structure in the page folders instead of using pathPrefix and then uploading at the site root. Will have an experiment to make sure though...

…estion

Jeddf · 2019-10-16T21:17:15Z

I miss in the further steps section:

how I port a second/third folder to Gatsby? There is only one pathPrefix: Do i need a second, third Gatsby for this?

how I port the full site to Gatsby? (By add who folder to the src director, removing pathPrefix ...)

Done! They sorta popped out as one section together, think it rounds the guide off nicely, really appreciate the suggestion. Interested to hear your thoughts on it @muescha. I also added a bit about Gatsby handling assets, the next steps section is maybe looking a little heavy now!

muescha

it looks great to me.

some fixes and some questions comes up added

muescha · 2019-10-16T22:25:17Z

docs/docs/porting-part-of-a-html-site-to-gatsby.md

+    └── shrinking.js
+```
+
+2. The `pathPrefix` configuration option is no longer needed as the Gatsby application will now be served at the root of the site alongside the remaining HTML files.


but we still need the build with --withPaths for the assets?

Aye, there's a note up with the build step on line 479 that I think does the trick in explaining this:

> **Note**: The --prefix-paths option _must_ be used for path and asset prefixes to be applied

Thinking they'll find themselves back up there when building again if they hit problems.

Here's a question: what does the asset prefix stuff gain? Could this guide be simplified and include global CSS instead?

Looking again at the asset prefix docs page as well, I think it'll follow on from this guide really cleanly for the reader. I'll take a pass through to take out asset-prefix from the example, host the whole gatsby build output at the /who path and move the css, png etc to assets folder on the website-domain.

What do you mean by global CSS? Directly importing a CSS file in the Layout.js file? I'd lean more toward keeping a basic link tag so the method stays consistent with the remaining HTML pages, so

<link rel="stylesheet" type="text/css" href="https://gatsby-html-partial-assets.s3.eu-west-2.amazonaws.com/style.css" />

becomes

<link rel="stylesheet" type="text/css" href="/assets/style.css"/>

muescha · 2019-10-16T22:26:28Z

docs/docs/porting-part-of-a-html-site-to-gatsby.md

+
+2. Adjust the `pathPrefix` Gatsby configuration option to reflect the new root path at which the Gatsby application will be served.
+
+3. Ensure the `to` props on all Gatsby `<Link>` components are correct relative to `/src/pages/` as the application root.


general question (maybe adressed also early on this page): here we use <Link> for all pages in the old and new website or only for the new website (preloading is compatible with old html pages?)

i think you adressed this in the next point 3

The docs warn against using <Link> for external sites, I took that to mean anything outside the Gatsby app but looking back it may just be external to the website as a whole.

Once pathPrefix is not being used in a project, I don't know if there is a reason not to use <Link> for non Gatsby, internal pages. That is a possible small clarification to add to the Link page. Will dig a little to find the answer.

docs/docs/porting-part-of-a-html-site-to-gatsby.md

Co-Authored-By: Michael <184316+muescha@users.noreply.github.com>

marcysutton

Thanks so much for working on this! I left some suggestions for adjusting the text; please let me know if you have any questions when going through them. Something to keep in mind: I do think this should exist as a Reference Guide rather than a tutorial, even if it is a lot of a how-to. Perhaps some adjustments to headings and text could help the sections stand on their own? That's what would make it more of a guide than a tutorial.

docs/docs/porting-part-of-a-html-site-to-gatsby.md

marcysutton · 2019-10-18T19:02:00Z

docs/docs/porting-part-of-a-html-site-to-gatsby.md

+
+## Why Gatsby?
+
+### Web building blocks


I love the way you're thinking here, but these paragraphs detract from the purpose of a reference guide: to provide reference material for doing the task of porting a site to Gatsby. Perhaps we could summarize this section and link off to a different page on "Why Gatsby"? It is unusual for a reference guide or even a tutorial to have this much background on the page itself. Here's a page we could briefly introduce and link off to instead, which would shorten this quite a bit:

https://www.gatsbyjs.org/docs/gatsby-core-philosophy/

Very much agree, I've tried to help the reader focus in the rest of the page but this section would certainly make my mind wander. Pushing up a rewrite shortly, keen to hear your thoughts on it.

marcysutton · 2019-10-18T19:03:42Z

docs/docs/porting-part-of-a-html-site-to-gatsby.md

+      └── sam-surgeon.html
+```
+
+The `/who` section of the site is a great candidate for porting as it is all within a single folder. Through this guide, you will develop the ported Gatsby section in isolation before integrating into the site.


What does isolation refer to here? Can we add something to explain it a bit further, such as "you will develop the ported Gatsby section in isolation before integrating into the site by _____"?

Agreed, pushing up this addition shortly.

marcysutton · 2019-10-18T23:14:27Z

docs/docs/porting-part-of-a-html-site-to-gatsby.md

+    └── shrinking.js
+```
+
+2. The `pathPrefix` configuration option is no longer needed as the Gatsby application will now be served at the root of the site alongside the remaining HTML files.


Here's a question: what does the asset prefix stuff gain? Could this guide be simplified and include global CSS instead?

docs/docs/porting-part-of-a-html-site-to-gatsby.md

marcysutton

Thanks so much for working on this! I left some suggestions for adjusting the text; please let me know if you have any questions when going through them. Something to keep in mind: I do think this should exist as a Reference Guide rather than a tutorial, even if it is a lot of a how-to. Perhaps some adjustments to headings and text could help the sections stand on their own? That's what would make it more of a guide than a tutorial.

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

- Briefly explain JSX and add in some mentions. - Expand and clarify JavaScript / JSX passages. Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Jeddf · 2019-10-22T21:16:36Z

Yeh! Now that the page is about porting HTML in general, tangling it up with path prefix all the way through is possibly confusing.

Maybe there are 2 topics here really. Migrating an HTML site to gatsby and nesting a Gatsby app into an HTML site. Can flip it to a complete porting first then talk about the prefix stuff and it'll be easier to link out at that point.

I'll extract path prefix as a next iteration. Then take another look at what can be linked out/moved to recipes/other pages. I reckon the change will make lotsa other pages more applicable.

Jeddf · 2019-10-23T22:18:22Z

I've restructured it to be a direct porting from HTML guide 🎉 It feels clearer, I like how it's shaken out. Screenshot is not updated unfortunately.

Will take a pass tomorrow over it with the gatsby docs, to see what I think can be linked out/moved to recipes/other pages.

muescha · 2019-10-24T16:38:10Z

Looks very good
Maybe you also mention the pathPrefix in the last section if someone like more strong encapsulated parts? Just a small not with a link to a receipt or doc page

…rkup

Jeddf · 2019-10-25T08:01:25Z

Yeh I think enough should be done in the page for a user to be able to locate the prefix instructions at a logical spot and understand the use case. Added a hosting section with enough direction to apply pathPrefix while also linking out to the docs pages for path and asset prefix. What do you think @muescha?

I'm a little concerned about having included explicit instructions in the flow for a step that's optional. Hopefully it's made clear enough by having a repeated build bash line though.

Jeddf · 2019-10-31T23:42:34Z

Happy Halloweeeeen @marcysutton! I've addressed your suggestions and made an additional structural change to suit it now not just being a partial porting guide as suggested by @muescha. The core example is now a full HTML site migration, and pathPrefix is offered as an optional step around build and deploy if the site is not to be hosted at the domain root.

The opening positions it relative to the main tutorial. Despite it being somewhat similar, I think there is still significant value in providing a shorter, focused path for new users to get from HTML to a Gatsby static site.

It could go full reference guide by hedging closer to the format of the CRA porting page and addressing each of the points somewhat in isolation rather than structuring it around an overall example. I think in that case though you'd ask a little more of the reader by having them need to thread together an end to end development flow themselves. I'm assuming the HTML porting user's current build process will likely just be edit file and upload/commit. While the CRA structure suits addressing points likely to be hit when adapting their existing workflow, the HTML user is likely to be starting a development flow from scratch, so structuring around an example and walkthrough makes sense.

🎃

…-html

marcysutton

This is so cool! I think it's going to be very useful to users. I think it's worth tweaking slightly and merging in this format. It's had a lot of work go into it already, and I think it's in great shape. Thank you so much for all of your hard work on this, and let me know if you have any questions!

docs/docs/porting-an-html-site-to-gatsby.md

marcysutton · 2019-11-02T02:46:05Z

docs/docs/porting-an-html-site-to-gatsby.md

+
+If the Gatsby site is to be hosted at a non-root path, e.g. `example.com/blog/`, Gatsby needs to be informed so page and asset links in the built output can be prefixed.
+
+[Path prefix](/docs/path-prefix/) is the Gatsby option for setting a non-root hosting path. Here is the example project `gatsby-config.js` file with a path prefix added for `/blog`:


This is nice! 👍

docs/docs/porting-an-html-site-to-gatsby.md

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

muescha · 2019-11-04T16:23:47Z

#13813 requests some incremental change. This is lost now In the rewriting.

Maybe at some point we can stop in the middle (maybe after changing the who section) and show how to deploy an half migrated site?

Maybe to answer the questiin: Can the files from /public mixed with the source files on the server?

marcysutton · 2019-11-05T04:58:55Z

#13813 requests some incremental change. This is lost now In the rewriting.
Maybe at some point we can stop in the middle (maybe after changing the who section) and show how to deploy a half migrated site?

That's a good point. @Jeddf I'd recommend addressing it at the beginning of the doc to help the reader establish whether they want to read the whole thing by talking specifically about those two use cases. At the end of the intro paragraph, you could say something like "This doc could also be applied to migrate a section of a site to be served next to existing files; pay extra attention to the section on Hosting..."

Maybe to answer the question: Can the files from /public mixed with the source files on the server?

That could be addressed in the Building & Deploying section, near where you talk about hosting and the --path-prefix.

Jeddf · 2019-11-06T18:30:35Z

Great point, it definitely no longer addressed the original issue.

I've used the note format that I've seen in a few other docs to add to the introduction. Almost added a new heading with the extra note for the section porting part, but having it just be part of the hosting section makes it clearer it's optional I think.

…-html

marcysutton

I think this one has gone through sufficient rounds of feedback, so we should merge it in (we can always make updates later if needed)! Thanks so much to @Jeddf for your work on this. It's going to be very helpful to users!

gatsbot · 2019-11-25T23:42:14Z

Holy buckets, @Jeddf — we just merged your PR to Gatsby! 💪💜

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

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 Gatsby t-shirts, stickers, hats, scrunchies, and much more. (You can also unlock even more free swag with 5 contributions — wink wink nudge nudge.) See gatsby.dev/swag for details.
We just invited you to join the Gatsby organization on GitHub. This will add you to our team of maintainers. Accept the invite by visiting https://github.com/orgs/gatsbyjs/invitation. By joining the team, you’ll be able to label issues, review pull requests, and merge approved pull requests.

If there’s anything we can do to help, please don’t hesitate to reach out to us: tweet at @gatsbyjs and we’ll come a-runnin’.

Thanks again!

docs: guide for porting part of a html site to gatsby

8a36bf2

Jeddf requested review from a team as code owners October 14, 2019 12:31

Jeddf added 2 commits October 14, 2019 16:01

fix: add missing normalize.css file to trees, build sentence rewrite

004a503

fix: change links to be relative paths

07ba175

gillkyle reviewed Oct 15, 2019

View reviewed changes

gillkyle added the type: documentation An issue or pull request for improving or updating Gatsby's documentation label Oct 15, 2019

Jeddf and others added 4 commits October 15, 2019 19:15

Apply suggestions from code review

8ee904a

Co-Authored-By: Kyle Gill <kylerobertgill@gmail.com>

Apply suggestions from @gillkyle code review

35035a3

Clearer and Consistenter(heh) prefix descriptions

d050fb5

format is aggressive about wrapping here, switching to start/end marks!

6c33920

bracket typo, square the curl

b0ad1b4

marcysutton self-assigned this Oct 15, 2019

muescha reviewed Oct 16, 2019

View reviewed changes

Apply suggestions from code review

4e5c33e

Co-Authored-By: Michael <184316+muescha@users.noreply.github.com>

parting more ports and the complete Gatsby section, per @muescha sugg…

fd9ceb1

…estion

muescha reviewed Oct 16, 2019

View reviewed changes

Update docs/docs/porting-part-of-a-html-site-to-gatsby.md

3d9cdec

Co-Authored-By: Michael <184316+muescha@users.noreply.github.com>

marcysutton suggested changes Oct 18, 2019

View reviewed changes

Jeddf and others added 6 commits October 21, 2019 18:20

Make page more general, for porting part and the whole

dff8915

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Apply suggestions from code review

cb8215d

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Style guide: less we more you

a2dedc1

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Apply suggestions from code review

add945b

- Briefly explain JSX and add in some mentions. - Expand and clarify JavaScript / JSX passages. Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Review: Clarify tooling and building points.

fe961b9

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

condense why section and link off to core philosophy

997b7d8

Jeddf added 2 commits October 23, 2019 23:09

restructure for full html site port, with note for prefix options

e6bc535

fix out of date directory name

52f49f8

correct contradicting sentence about not changing copied over html ma…

b4f84a0

…rkup

Jeddf changed the title ~~docs: guide for porting part of a html site to gatsby~~ docs: guide for porting an html site to gatsby Oct 25, 2019

expand opening to position guide relative to main tutorial

fec5b54

Jeddf requested a review from marcysutton October 31, 2019 23:25

Merge remote-tracking branch 'upstream/master' into docs/porting-part…

c76df48

…-html

marcysutton suggested changes Nov 2, 2019

View reviewed changes

Jeddf and others added 3 commits November 2, 2019 08:48

Apply suggestions from code review

87e94b0

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

fix gatsby-site path roots

bf37826

Apply suggestion from code review - gatsby serve tip

767884a

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Jeddf requested a review from marcysutton November 2, 2019 11:23

marcysutton mentioned this pull request Nov 6, 2019

chore: update a few reference guide overview pages #19296

Merged

Jeddf added 2 commits November 6, 2019 18:05

add partial porting note to introduction and hosting section

02061cc

consistent flag --

eed19f1

Merge remote-tracking branch 'upstream/master' into docs/porting-part…

18c2216

…-html

marcysutton added this to In progress in Documentation Roadmap via automation Nov 25, 2019

marcysutton moved this from In progress to PRs for Review in Documentation Roadmap Nov 25, 2019

marcysutton approved these changes Nov 25, 2019

View reviewed changes

marcysutton merged commit ca4a65c into gatsbyjs:master Nov 25, 2019

Documentation Roadmap automation moved this from PRs for Review to Done Nov 25, 2019


		2. Adjust the `pathPrefix` Gatsby configuration option to reflect the new root path at which the Gatsby application will be served.

		3. Ensure the `to` props on all Gatsby `<Link>` components are correct relative to `/src/pages/` as the application root.


		If the Gatsby site is to be hosted at a non-root path, e.g. `example.com/blog/`, Gatsby needs to be informed so page and asset links in the built output can be prefixed.

		[Path prefix](/docs/path-prefix/) is the Gatsby option for setting a non-root hosting path. Here is the example project `gatsby-config.js` file with a path prefix added for `/blog`:

docs: guide for porting an html site to gatsby #18609

docs: guide for porting an html site to gatsby #18609

Conversation

Jeddf commented Oct 14, 2019 • edited

Description

Related Issues

Preview (in 2 parts 😂) - updated for 02061cc

gillkyle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jeddf commented Oct 15, 2019

muescha left a comment

Choose a reason for hiding this comment

muescha commented Oct 16, 2019

Jeddf commented Oct 16, 2019 • edited

Jeddf commented Oct 16, 2019

muescha left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton left a comment

Choose a reason for hiding this comment

Jeddf commented Oct 22, 2019 • edited

Jeddf commented Oct 23, 2019 • edited

muescha commented Oct 24, 2019 • edited

Jeddf commented Oct 25, 2019 • edited

Jeddf commented Oct 31, 2019

marcysutton left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

muescha commented Nov 4, 2019 • edited

marcysutton commented Nov 5, 2019

Jeddf commented Nov 6, 2019

marcysutton left a comment

Choose a reason for hiding this comment

gatsbot bot commented Nov 25, 2019

Jeddf commented Oct 14, 2019 •

edited

Preview (in 2 parts 😂) - updated for `02061cc`

Jeddf commented Oct 16, 2019 •

edited

muescha left a comment •

edited

Jeddf commented Oct 22, 2019 •

edited

Jeddf commented Oct 23, 2019 •

edited

muescha commented Oct 24, 2019 •

edited

Jeddf commented Oct 25, 2019 •

edited

muescha commented Nov 4, 2019 •

edited