Web Fundamentals on DevSite
Welcome to the new Web Fundamentals! An effort to showcase best practices and tools for modern Web Development.
What's changed?
- We're now using the DevSite infrastructure
- New style guide
- New widgets allow inline JavaScript, common links, related guide and more
- Jekyll has been eliminated. Instead, pages are rendered at request time
- Front-matter has been eliminated from the markdown, but files now require a simple set of tags
What stays the same?
- GitHub is still our source of truth for content,
- We want your contributions, either PRs, issues, whatever!
- The latest is staged at https://web-central.appspot.com/web/
Cloning the repo
If you have a high-bandwidth connection, I recommend starting with a fresh clone of the repo.
git clone https://github.com/google/WebFundamentals.git
Getting set up
The new DevSite infrastructure simplifies the dependencies a lot. Ensure that you have Python, Node 10-12, and the Google Cloud SDK already installed.
Login to Google Cloud via command line.
- Run
npm install
(needed for the build process)
Building the auto-generated files
Some files (contributors includes, some pages for updates, showcases, etc.) are automatically generated. The first time you clone the repo and run npm install
, this is done for you. However, when you add a case study, update, etc., you'll need to re-build those files using:
npm run build
Starting Local Server
To view the site locally, just run:
npm start
Note: The first time you start the server, you may need to run start-appengine.sh
and answer any prompts provided by dev_appserver.py
.
Updating the code labs
To update the Code Labs, you'll need the claat
tool and access to the original Doc files. This will likely only work for Googlers.
- Download the
claat
tool and place it in yourtools
directory - Run
tools/update-codelabs.sh
- Check the latest changes into GitHub
Starting the development server
- Run
npm start
in the terminal.
Testing your changes before submitting a PR
Please run your changes through npm test before submitting a PR. The test looks for things that may cause issues with DevSite and tries to keep our content consistent. It's part of the deployment process, so PRs will fail if there are any errors! To run:
npm test
Add new Understanding Resource Timing documentation.
Adding a new page specifically for resource timing. Moving the data from the existing network page to it and expanding upon it.
Sorry @kaycebasques, you know I can't test locally. So please let me know what is needed to make sure this is linked properly from places like the DevTools landing page's Network tab. If it isn't automatically done.
Web Performance Optimization with webpack
What's changed, or what was fixed?
Target Live Date: Probably January?
gulp test
locally and all tests pass. (There’re a few<script>
-related warnings, but these<script>
blocks are code examples)type-something
label. (Not sure what’s this and haven’t found related info)R: @petele
I also have a few formatting-related questions:
For some reason, “Note:” blocks were recognized during one server launch and weren’t recognized during another. Probably that’s my local buggy installation, but IDK. Could we check this on the proper environment?
Locally,
{: .hide-from-toc }
wasn’t hiding “Further reading” headers from TOC (see e.g.decrease-frontend-size.md
. Could you please check if I’m using them properly?Is there a way to enable diff-like formatting (see below) for specific code blocks? I use it in a few code examples.
Added "How to Think About Speed Tools" article.
This PR contains new content mocked up for /web in the performance section entitled "How to Think About Speed Tools" requested by @addyosmani.
Webpack guide updates for webpack 4
What's changed, or what was fixed?
Target Live Date: 2018-02-24 (webpack 4 release)
gulp test
locally and all tests pass. (I’m on windows, and it’s hard here, sorry.)type-something
label.Please don’t merge this yet. I was unable to test some plugins with webpack 4 because they weren’t made compatible yet. Here’s what left to do:
InlineChunkWebpackPlugin
instructions and update them if necessaryWebpackManifestPlugin
instructions and update them if necessaryI’ll re-check the status of these plugins on the next week.
Feel free to review the remaining text meanwhile, it should be stable.
CC: @petele @addyosmani
[Translation it] Performance > Optimizing content efficiency > Automating-image-optimization
Italian translation of Performance > Optimizing Content Efficiency > Automating-image-optimization.
Please review by @carlaofarrell
Check out a review request at GitLocalize
Add media video preload article
This is my WIP (not ready at all) article for video preload. Let's use it to get feedback.
Live preview at https://pr-4744-dot-web-central.appspot.com/web/fundamentals/media/fast-playback-with-video-preload
Update guidance on RAIL
What's changed, or what was fixed?
This is an update to our RAIL guidance including affordances for our newer loading metrics. It also introduces a more explicit call out for goals and guidelines for each area.
The goals and guidelines call outs are something the Chrome Speed Metrics team felt would make for a more clear framing of RAIL.
Fixes: #5464 with more details on what changed
Target Live Date: December 15th
gulp test
locally and all tests pass.type-something
label.R: @petele @Meggin @kaycebasques
Notes: This is my last day in the office for this year. If anyone would like to take on directly editing/addressing further changes before the new year, I'm more than happy for them to do so :)
Make the homepage look more like the documentation page
Feedback for: /fundamentals/getting-started/web-starter-kit/setting-up.html
Under the Sass section you say that once you install Gulp globally that Sass will be available to you. I am pretty sure that the gulp-ruby-sass still relies on ruby and sass, so you still need to install ruby and sass separately for Windows Os. Otherwise nice articles!
See gulp-ruby-sass page
[EN] Feedback for: /web/tools/chrome-devtools/profile/evaluate-performance/performance-reference?hl=en
It seems that the following guides:
Are completely out of date, as far as I can tell. The Timeline view that I have in Version 47.0.2526.80 (64-bit) looks like:
Which doesn't seem to correspond at all to the view those articles use:
It wouldn't be a big deal if it was just a small UI update, but it seems that the feature set described in those articles have been replaced, or at least obscured. Things like Events/Frames mode seem to be gone, and I can't find any newer posts with updated information on the Timeline view.
At the very least, if there is a post I'm missing, this article should note that the view is out of date.
Localization Support: Quick questions before translating WebFundamentals
Hi
I just try to translate WebFundamentals into Korean with some developers, and have some quick questions before diving it. :)
Q. Is it possible to commit translated pages one by one?
For example, when I translated article in HTML5Rocks, I added the directory 'ko' in same level of place of source tree, and then translated it. If users visit an article without its translation, H5R shows a sorry message and delivery its default version. I think that it's available at WebFundamentals as I can see from Translation Guide. I just want to confirm it again before arranging our translation plan. :)
Q. How can we track changes of documents?
WebFundamentals' articles have been updating frequently. This means translator have to track these changes like below:
Suggestion: support workflow tools for translation
I think the most simple solution is that adding current source hash to the translation. However, human can take mistakes easily, I hope some utilities for initialization of translation and searching out-dated documents like below:
Initializing structure or page for the translation
Before translating article(s), Translator initialize structure or page. I guess this can be ignored on working process. I just suggest this to avoid copying unnecessary resources.
Finding outdated translations
Then translator can update the translation according to its history.
Update hashes
This will add the version of source hash to the translation, when translator want to update it.
Then commit translation and send Pull Request or Update hash before update.
Of course, above things are just sketchy imaginations. If you have any suggestion, It helps us. Thanks. :)
[Remote Debugging]
Welcome! Please use this template for reporting documentation issues on https://developers.google.com/web/.
For questions about Chrome DevTools, checkout the
google-chrome-devtools
tag on StackOverflow. For questions about Chrome, check thegoogle-chrome
tag. If you think you've found a Chrome bug, check out our feedback page for more details on how to file it.Page Affected: https://developers.google.com/web/TODO
What needs to be done?
Please provide description of what's needs to be done here. Please be sure to include the link to the original page and any supporting links/data.
type-something
label has been added.section-something
label has been added.[Remote Debugging]
Welcome! Please use this template for reporting documentation issues on https://developers.google.com/web/.
For questions about Chrome DevTools, checkout the
google-chrome-devtools
tag on StackOverflow. For questions about Chrome, check thegoogle-chrome
tag. If you think you've found a Chrome bug, check out our feedback page for more details on how to file it.Page Affected: https://developers.google.com/web/TODO
What needs to be done?
Please provide description of what's needs to be done here. Please be sure to include the link to the original page and any supporting links/data.
type-something
label has been added.section-something
label has been added.Verbal fix on documentation's blue "activation" note section
Page Affected: https://developers.google.com/web/ilt/pwa/introduction-to-service-worker#activation
What needs to be done?
Typo fix on blue "activation" note section: Remove the double
the
on sentence: ... because the new page will be requested before the the current page is unloaded ...PageSpeed Insights can't realize CSS Cascade Layers.
Hi,
I use PageSpeed Insights to check web page. I found my CLS score is ugly then I realize CSS losing (from preview). I use CSS Cascade Layers for web page. I wonder can't PageSpeed Insights realize CSS Cascade Layers ?
Here comes my style code.
Thank you for reading.