├── README.md └── _config.yml /README.md: -------------------------------------------------------------------------------- 1 | # Static-Pages 2 | Guide/comparison of ways to create and host static pages 3 | 4 | ## What is a static webpage? 5 | Any webpage where all the content (HTML, JavaScript, CSS, images) is loaded in 6 | and rendered by the user's browser ("front-end"). There are some important 7 | benefits and limitations of this: 8 | 9 | - *Can* host freely/cheaply at a bunch of places, deploy and switch hosts 10 | easily. 11 | - *Can* be built with a variety of tools and play nicely with almost any 12 | language/framework/ecosystem. 13 | - *Can't* persist user data across sessions/devices (or need to rely on external 14 | service to do so, or can do 15 | [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) 16 | but that won't go across devices and the user may wipe it). 17 | - *Can't* use a secret API key to connect to a service - anyone who loads the 18 | page could extract the key and abuse the service (and get your access 19 | suspended). Can still connect to unauthenticated APIs. 20 | 21 | Static just means "unchanging", and overall that's what static webpages are good 22 | for - content that doesn't change. However, front-end frameworks like 23 | [React](https://github.com/facebook/react) have blurred the lines a bit, and you 24 | can have a front-end application that is static from a code/infrastructure 25 | perspective but is still dynamic and engaging to the user. So get creative! Take 26 | advantage of the many tools and services available, and you can build an awesome 27 | webpage that maximizes the advantages and minimizes the disadvantages of being 28 | static. 29 | 30 | ## How can I build a static webpage? 31 | The simplest thing to do is just build it "by hand" - that is, use a text editor 32 | and write .html, .css, and .js files to your hearts content. This "back to 33 | basics" approach can be appropriate for things that are really simple, really 34 | won't need lots of updates, and also if you're just feeling nostalgic or want to 35 | reinforce your knowledge on the basics (which helps with everything else). 36 | 37 | For more substantial and/or frequently updated pages, it's a good idea to use a 38 | static site generator - a tool that renders all the actual HTML/JS/CSS based on 39 | templates, configuration settings, and usually 40 | [Markdown](https://daringfireball.net/projects/markdown) files for the actual 41 | content. There is an absurd number of these generators, you can 42 | [check out popular ones here](https://www.staticgen.com). 43 | 44 | With many options come many opinions, but in general you can't go wrong with 45 | anything that is well-maintained and has a good community around it. It's also a 46 | good idea to pick something that is either a language/framework that you know 47 | about or are interested in learning more - as you start to try to customize your 48 | page you'll find yourself digging in to how the generator actually works, so 49 | it's good to choose accordingly. 50 | 51 | Some top highlights: 52 | 53 | - [Jekyll](https://jekyllrb.com) - Ruby, it's been around (mature/stable), and 54 | is what actually powers GitHub pages if you just push Markdown files (see also: 55 | [Octopress](http://octopress.org)). 56 | - [Hexo](https://hexo.io) - Node.js, essentially a JavaScript take on Jekyll 57 | (compatible with the same Markdown and similar plugin ecosystem). 58 | - [Hugo](http://gohugo.io) - Go, *extremely fast*, great for generating *big* 59 | sites. Also just a single binary, so no need to mess with package management or 60 | dependencies for installation. 61 | - [Pelican](https://blog.getpelican.com) - Python, supports a variety of content 62 | formats and integrates/imports from WordPress and others. 63 | - [Gatsby](https://github.com/gatsbyjs/gatsby) - React, creates a "dynamic" 64 | static site (a Single Page Application where everything is loaded on the initial 65 | request and further clicking/browsing doesn't refresh the page). 66 | - [Brunch](http://brunch.io) - JavaScript, not really a blog generator like the 67 | above but rather a build tool/pipeline to simplify making a modern static site. 68 | 69 | ## How/where can I deploy a static webpage? 70 | One of the big advantages of static webpages is the ease and flexibility of 71 | deployment. To deploy all you do is copy the files to the server that serves 72 | them - that's it! The only dependency is a basic webserver that listens to and 73 | returns basic HTTP requests. You can of course build/deploy your own server (and 74 | that is an excellent exercise), but for our purposes here we'll consider some of 75 | the many excellent free/cheap services that do this for you. 76 | 77 | ### Start Simple - GitHub Pages 78 | [GitHub Pages](https://pages.github.com) are a great way to get started, and 79 | actually still a strong choice as you scale up. It's a free service, but can 80 | handle substantial traffic, supports custom URLs/domains, and gives SSL. The 81 | deploy process is simple - just enable GitHub Pages in the settings page for 82 | your repository. You have a few options: 83 | 84 | - Use the `master` branch - this means any content in the master branch of 85 | `github.com/user/repo/` will be served from `user.github.io/repo/`. Good for 86 | repos that are entirely meant to be webpages. 87 | - Use the `gh-pages` branch - content in `gh-pages` will be served per the same 88 | URLs as above. Good for repos that use a tool/template to generate the page (you 89 | save that to your `master` branch and save the built output to `gh-pages`). 90 | - Use the `/docs` folder on the master branch - good for non-webapp projects 91 | (e.g. tools, games, etc.) where you want to serve the documentation as a page. 92 | 93 | This particular repository is using the first approach, so you can read this 94 | very file from [https://lambdaschool.github.io/Static-Pages/](https://lambdaschool.github.io/Static-Pages/) 95 | (if you're not already). Note that if you do this you will not see the true 96 | Markdown source - instead, it will be rendered to HTML by Jekyll (mentioned 97 | earlier). You can even apply themes and generally maintain a simple webpage on 98 | GitHub without writing a line of HTML - read 99 | [their Jekyll documentation](https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/) 100 | for more details. 101 | 102 | The deploy process is as simple as a `git push` of your content to the correct 103 | branch or folder. There exist packages to script/automate this, and you can 104 | write your own fairly easily. Also note that most GitHub competitors have 105 | similar services 106 | ([Bitbucket](https://confluence.atlassian.com/bitbucket/publishing-a-website-on-bitbucket-cloud-221449776.html), 107 | [GitLab](https://about.gitlab.com/features/pages/), etc.), and this competition 108 | helps prevent lock-in (you can pretty easily move your content between them). 109 | Configuring these services is a matter of reading their documentation and 110 | browsing their setting pages, but for the most part things like custom domains 111 | and SSL certificates should be straightforward or possibly automatic. 112 | 113 | You can also find tools that automate this process, or write your own script 114 | once you've settled on a workflow. Search [npm](https://npmjs.com) or your 115 | preferred package ecosystem and see what options exist - but just doing it 116 | directly in git is simple enough that it's good to understand it there too. 117 | 118 | ### Dedicated Hosts - Netlify, Surge, Forge 119 | If you want a service that just hosts pages, and doesn't offer it as a simple 120 | "add-on" for source code hosting, there are plenty of options. The focus here is 121 | services meant for coders - so you can interact with them and push content to 122 | them from the command line. Any web host that lets you upload content can work, 123 | but will be harder to automate and generally teach you less than using one of 124 | these options. 125 | 126 | - [Netlify](https://www.netlify.com/) - generous free tier, can connect to 127 | GitHub repositories, handle forms, facilitate A/B testing, continuous 128 | deployment, and more. Paid service is mostly for multiuser/enterprise. 129 | - [surge](http://surge.sh/) - similar to Netlify, good free tier, somewhat 130 | fewer options but if you don't intend to use them that may be a good thing. 131 | - [Forge](https://getforge.com/) - not free (but cheap to start), emphasis on 132 | speed and simplicity (optimized CDN and JS processing, cli for programmers but 133 | also supports just dragging/dropping files or connecting Dropbox for others). 134 | 135 | To actually use these services, just follow the tutorial/guide they offer - the 136 | general pattern is "install something (probably from npm), then run it." Try a 137 | few and see which one you like/works for your use case. 138 | 139 | There are other options, and these three may grow or disappear as the web 140 | continues to evolve. But there will likely always be options along these lines, 141 | and when you're making static content it's pretty easy to switch hosts - just 142 | push your content somewhere else! 143 | 144 | ### Big Players - Amazon, Google, Microsoft 145 | If you're making something Real - it's got to scale, it's got to load fast 146 | around the globe, and if it goes down pagers need to ring - then these are some 147 | options to consider. The line between the above simpler approaches and these 148 | "industry-grade" services isn't clear - especially if you go with a paid tier 149 | for the above services, you can definitely use it for something important. And 150 | even the free tiers are pretty reliable, but ultimately any free service doesn't 151 | provide the same sort of 152 | [SLA](https://en.wikipedia.org/wiki/Service-level_agreement) as a paid one. 153 | 154 | The other big reason to go with one of these is if you're using them anyway - 155 | each of these providers offers a slew of "cloud" services, and if you're using 156 | them for other things you may as well fire up their static file hosting. 157 | Compared to most of their other services, it's a fairly simple thing to do, and 158 | definitely scales great without costing too much. 159 | 160 | - [Amazon S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) - 161 | gives you "buckets" in different regions where you can upload your content. You 162 | may have to configure to make sure you've got good global coverage. Can be 163 | integrated with [CloudFront](https://aws.amazon.com/cloudfront/), the AWS CDN, 164 | to get even better performance around the world. 165 | - [Google Cloud Storage](https://cloud.google.com/storage/docs/hosting-static-website) - 166 | also uses "buckets", and also integrates with their 167 | [CDN](https://cloud.google.com/cdn/). Basically the Coke/Pepsi decision, and 168 | ultimately a decision that will be made for reasons besides static content. 169 | - [Azure Static Content Hosting](https://docs.microsoft.com/en-us/azure/architecture/patterns/static-content-hosting) - 170 | yes, Microsoft too has a cloud, though they use "blobs" rather than "buckets." 171 | They even have a 172 | [CDN](https://docs.microsoft.com/en-us/azure/cdn/cdn-cloud-service-with-cdn), 173 | and other services more or less comparable to Amazon and Google. They are a less 174 | popular choice for a variety of practical and historical reasons, but some 175 | clients will use them and they do offer generous free credits to a lot of users. 176 | 177 | How do you use these services? Read the documentation - it'll change fast, and 178 | generally involve lots of platform-specific settings and commands. The general 179 | concept though is the same - you just want to push some built static content to 180 | some path on the server that will be served via a webserver at some domain. 181 | 182 | ## Closing Notes and "Gotchas" 183 | Now you know the basics on what a static page is and how to get it out there - 184 | actually having static content worth putting out there is another matter. Lots 185 | of prominent developers maintain blogs (often built and hosted with the above 186 | tools/services), and getting in the habit of writing your thoughts and 187 | experiences with technology can help you organize and develop as well as market 188 | yourself. 189 | 190 | Some examples of high quality tech blogs for inspiration: 191 | 192 | - [Slack Engineering Blog](https://slack.engineering/) - gives great 193 | transparency and real technical details for what's going on at Slack. Simple but 194 | pleasing and highly readable design, and good quality writing (clearly it's a 195 | team effort, and they likely review each others posts before publishing). 196 | - [CSS-Tricks](https://css-tricks.com/) - great current front-end and design 197 | content, and as one would expect - very pleasing design. 198 | - [Smashing Magazine](https://www.smashingmagazine.com/) - more for developers 199 | and designers, and also a good example of a blog incorporated into a larger 200 | site. 201 | - [Beej's Bit Bucket](https://beej.us/blog/) - simple, readable, fast, Beej. 202 | 203 | Another typical use of static pages is for resumes - there are 204 | [tools specific for building them](https://github.com/salomonelli/best-resume-ever), 205 | and [lots](http://www.rleonardi.com/interactive-resume/) 206 | [of](https://magemello.github.io/) [crazy](http://liugle.com) 207 | [cool](http://www.anniwang.com) [examples](https://phildub.com) 208 | [out](http://www.kickjannic.com) [there](http://www.guillaumejuvenet.com). 209 | 210 | 211 | Besides what content to put out there, you're likely to run into issues as you 212 | get started, especially if you're doing something fancy like hitting an API. In 213 | particular, if your page is hosted by a service that uses HTTPS and you try to 214 | pull data from an API that uses HTTP (or vice-versa), it probably won't work. If 215 | you open up your browser debugger console you should see something like: 216 | 217 | ``` 218 | Mixed Content: The page at 'https://tsj7.github.io/YouTube-Clone/' was loaded 219 | over HTTPS, but requested an insecure resource 'http://www.youtube.com/embed/-40p_dZccPg'. 220 | This request has been blocked; the content must be served over HTTPS. 221 | ``` 222 | 223 | Basically, "don't cross the streams!" Ideally you should use HTTPS for both, it 224 | is the default for GitHub Pages and most other hosting services linked above. 225 | [Heroku](https://heroku.com) (another hosting service you may use for backends) 226 | also supports it, and most modern well-maintained APIs should as well. So the 227 | first thing to try if you hit this is to change whatever is HTTP to HTTPS and 228 | see if it works. 229 | 230 | If it doesn't, and you really need to use it, then (at least for prototyping) 231 | you can figure out disabling HTTPS for the other side. For GitHub Pages this is 232 | accessible under the settings for the repository. 233 | 234 | Other "gotchas" you may hit - with `git` based deployment, make sure you have 235 | the upstream repo set appropriately. `git remote -v` will verbosely list the 236 | remotes that git knows about, and can help debugging. And in general, proper git 237 | hygiene (regular commits with good messages, clearly named branches, etc.) will 238 | pay off, just as it does with regular development. 239 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-merlot --------------------------------------------------------------------------------