From 43ef209bad7a8995df077493e69d90bf177b5300 Mon Sep 17 00:00:00 2001 From: Stephen Wade Date: Sun, 31 Jan 2021 05:00:53 -0500 Subject: [PATCH] chore: Docs updates (#53) * chore: fix Eleventy spelling * chore: misc CONTRIBUTING.md updates * chore: fix GitHub capitalization * chore: fix HTML capitalization * chore: fix JavaScript capitalization * chore: misc README.md updates * chore: update slack.md to match modernweb-dev/web * chore: misc docs/about updates * chore: misc docs/blog updates * chore: misc docs/docs updates * chore: fix mdjs capitalization * chore: fix Markdown capitalization * chore: fix Rocket capitalization * chore: fix apostrophes * chore: fix TypeScript capitalization * chore: consistently capitalize headings * chore: misc docs/guides updates * chore: misc packages/building-rollup updates * chore: misc packages/check-html-links updates * chore: misc packages/cli updates * chore: misc packages/plugins-manager updates * chore: misc packages/search updates * chore: fix tests * chore: fix lints --- CONTRIBUTING.md | 28 +++---- README.md | 8 +- docs/_data/footer.json | 2 +- docs/_data/site.cjs | 2 +- docs/about/slack.md | 4 +- docs/about/sponsor.md | 2 +- docs/blog/introducing-check-html-links.md | 38 ++++----- docs/docs/configuration/overview.md | 20 ++--- .../setupEleventyComputedConfig.md | 10 +-- docs/docs/eleventy-plugins/mdjs-unified.md | 14 ++-- docs/docs/markdown-javascript/overview.md | 28 +++---- docs/docs/presets/blog.md | 2 +- docs/docs/presets/launch.md | 6 +- docs/docs/tools/check-html-links.md | 8 +- docs/docs/tools/plugins-manager.md | 6 +- docs/docs/tools/rollup-config.md | 14 ++-- docs/guides/configuration/getting-started.md | 8 +- docs/guides/first-pages/adding-pages.md | 16 ++-- docs/guides/first-pages/getting-started.md | 14 ++-- .../guides/first-pages/link-to-other-pages.md | 2 +- docs/guides/first-pages/manage-sidebar.md | 2 +- docs/guides/first-pages/urls.md | 6 +- docs/guides/first-pages/use-javascript.md | 6 +- docs/guides/go-live/overview.md | 12 +-- docs/guides/go-live/social-media.md | 16 ++-- docs/guides/presets/create-your-own.md | 6 +- docs/guides/presets/using-templates.md | 2 +- docs/index.md | 6 +- packages/blog/README.md | 2 +- packages/building-rollup/README.md | 2 +- packages/building-rollup/demo/js/demo-app.js | 2 +- packages/building-rollup/demo/ts/demo-app.ts | 2 +- .../test-node/createMpaConfig.test.js | 4 +- .../test-node/fixtures/mpa/index.html | 2 +- .../fixtures/mpa/sub-html/index.html | 2 +- packages/check-html-links/README.md | 6 +- packages/cli/README.md | 4 +- .../cli/demo/docs/blog/introducing-mdjs.md | 84 +++++++++---------- packages/cli/demo/docs/docs/modern-web.md | 8 +- packages/cli/demo/docs/index.md | 6 +- .../01-custom-elements.md | 4 +- .../codelabs/web-components-basics/index.md | 4 +- packages/cli/package.json | 2 +- packages/cli/preset/_data/site.cjs | 2 +- packages/cli/src/RocketCli.js | 2 +- .../RocketCli.computedConfig.test.js | 2 +- packages/cli/test-node/RocketCli.e2e.test.js | 2 +- .../docs/guides/index.11tydata.cjs | 4 +- .../rocket-config-in-template/docs/index.md | 2 +- .../e2e-fixtures/rollup-plugin/docs/index.md | 2 +- packages/drawer/README.md | 4 +- .../eleventy-plugin-mdjs-unified/README.md | 2 +- .../launch/preset/_assets/webmanifest.json | 2 +- packages/launch/preset/_data/footer.json | 2 +- packages/launch/preset/_data/site.cjs | 2 +- .../_includes/partials/head-content.njk | 2 +- packages/mdjs-core/demo/stories/README.md | 10 +-- packages/mdjs-preview/README.md | 2 +- packages/mdjs-story/README.md | 2 +- packages/navigation/README.md | 2 +- packages/plugins-manager/README.md | 2 +- packages/search/src/RocketSearch.js | 2 +- .../search/test-web/rocket-search.test.js | 2 +- tsconfig.browser-base.json | 2 +- tsconfig.node-base.json | 2 +- 65 files changed, 238 insertions(+), 240 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dee918f..bc3abff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,27 +4,27 @@ > Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. -First, create a fork of the [modernweb-dev/rocket](https://github.com/modernweb-dev/rocket) repo by hitting the `fork` button on the GitHub page. +First, create a fork of the [modernweb-dev/rocket](https://github.com/modernweb-dev/rocket) repository by hitting the `fork` button on the GitHub page. -Next, clone our repository onto your computer with this command (replacing YOUR_USERNAME with your actual GitHub username) +Next, clone our repository onto your computer. ```sh git clone git@github.com:modernweb-dev/rocket.git ``` -Once cloning is complete, change directory to the repo. +Once cloning is complete, change directory to the repository. ```sh cd rocket ``` -Now add your fork as a remote +Now add your fork as a remote (replacing YOUR_USERNAME with your GitHub username). ```sh -git remote add fork git@github.com:/rocket.git +git remote add fork git@github.com:/rocket.git ``` -Create a new local branch +Create a new local branch. ```sh git checkout -b my-awesome-fix @@ -32,7 +32,7 @@ git checkout -b my-awesome-fix ## Preparing Your Local Environment for Development -Now that you have cloned the repository, ensure you have [yarn](https://classic.yarnpkg.com/lang/en/) installed run the following commands to set up the development environment. +Now that you have cloned the repository, ensure you have [yarn](https://classic.yarnpkg.com/lang/en/) installed, then run the following commands to set up the development environment. ```sh yarn install @@ -42,25 +42,25 @@ This will download and install all packages needed. ## Making Your Changes -Make your changes to the project. Commits are linted using precommit hooks, meaning that any code that raises linting error cannot be committed. In order to help avoid that, we recommend using an IDE or editor with an eslint plugin in order to streamline the development process. Plugins are available for all the popular editors. For more information see [ESLint Integrations](https://eslint.org/docs/user-guide/integrations) +Make your changes to the project. Commits are linted using precommit hooks, meaning that any code that raises a linting error cannot be committed. In order to help avoid that, we recommend using an IDE or editor with an ESLint plugin in order to streamline the development process. Plugins are available for all the popular editors. For more information see [ESLint Integrations](https://eslint.org/docs/user-guide/integrations) -### Compiling the typescript code +### Compiling the TypeScript Code -If you're making cross-package changes, you need to compile the typescript code. We recommend executing `tsc:watch` from the root of the package and keeping that running while you make your changes. +If you're making cross-package changes, you need to compile the TypeScript code. We recommend executing `tsc:watch` from the root of the package and keeping that running while you make your changes. -### Running tests +### Running Tests To run the tests of a package, it's recommended to `cd` into the package directory and then using `yarn test` to run them. This way you're only running tests of that specific package. -### Integration testing +### Integration Testing To see how your changes integrate with everything together you can use the `test-runner` package. There are different commands in this package which you can execute to trigger different scenarios in the test runner. -## Adding new packages +## Adding New Packages For all projects the tsconfig/jsconfig configuration files are auto generated. You need to add an entry to the [./workspace-packages.ts](./workspace-packages.ts) to let it generate a config for you. After adding an entry, run `yarn update-package-configs` to generate the files for you. -## Create a Changeset +## Creating a Changeset If you made changes for which you want to trigger a release, you need to create a changeset. This documents your intent to release, and allows you to specify a message that will be put into the changelog(s) of the package(s). diff --git a/README.md b/README.md index 50bae93..821f742 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -> This project is in it's BETA phase +> This project is in its BETA phase

eleventy, Rollup, and Modern Web. +- **Meta Framework:** Build on top of giants like Eleventy, Rollup, and Modern Web. - **Powerful Default Template:** Provide content and you are ready to go. - **Small:** No overblown tools or frontend frameworks, add JavaScript and/or Web Components only on pages where needed.. @@ -41,12 +41,12 @@ Explore the Rocket Guides  β–Ά

-## The goal for Rocket +## The Goal for Rocket > Our goal is to provide developers with a meta framework for static websites with a spricle of JavaScript. Get a site up and running in no time and focus on the content. -You can still tweak every details of every underlying tool that get's used. +You can still tweak every detail of every underlying tool that gets used. Rocket is part of the [Modern Web Family](https://twitter.com/modern_web_dev). diff --git a/docs/_data/footer.json b/docs/_data/footer.json index 6b918ea..77a00e7 100644 --- a/docs/_data/footer.json +++ b/docs/_data/footer.json @@ -16,7 +16,7 @@ "name": "Follow", "children": [ { - "text": "Github", + "text": "GitHub", "href": "https://github.com/modernweb-dev/rocket" }, { diff --git a/docs/_data/site.cjs b/docs/_data/site.cjs index ac8a77f..1a97987 100644 --- a/docs/_data/site.cjs +++ b/docs/_data/site.cjs @@ -3,7 +3,7 @@ module.exports = async function () { dir: 'ltr', lang: 'en', name: 'Rocket', - description: 'Rocket is the way to build fast static websites with a sprinkle of javascript', + description: 'Rocket is the way to build fast static websites with a sprinkle of JavaScript', socialLinks: [ { name: 'GitHub', diff --git a/docs/about/slack.md b/docs/about/slack.md index 567d9cb..3904bf1 100644 --- a/docs/about/slack.md +++ b/docs/about/slack.md @@ -1,5 +1,5 @@ # Slack -You can also find us on the Polymer slack in the [#open-wc](https://slack.com/share/IUQNUPWUF/awabyN8iYH4dXX6aGpu16ES9/enQtOTc2Nzc2ODEyOTY3LWM5ZGExNGFiMmM4NDY2YWI2MzYwOGY5ZTNlZjk4OGU4NTFhMGJjNmVhNGI4MzVlNTMwNGRiNGIxNjc4MGJhNDg) channel. +You can also find us on the Polymer Slack in the [#open-wc](https://polymer.slack.com/archives/CE6D9DN05) channel. -You can join the Polymer slack by visiting https://www.polymer-project.org/slack-invite. +You can join the Polymer Slack by visiting [https://www.polymer-project.org/slack-invite](https://www.polymer-project.org/slack-invite). diff --git a/docs/about/sponsor.md b/docs/about/sponsor.md index b3dc32f..0a229fb 100644 --- a/docs/about/sponsor.md +++ b/docs/about/sponsor.md @@ -6,4 +6,4 @@ eleventyNavigation: We currently can only accept sponsoring in the form of services or contributions. -If you are interested in monetary sponsoring please [let as know as](mailto:hello@modern-web.dev). +If you are interested in monetary sponsoring please [let us know](mailto:hello@modern-web.dev). diff --git a/docs/blog/introducing-check-html-links.md b/docs/blog/introducing-check-html-links.md index 271b07c..ff19302 100644 --- a/docs/blog/introducing-check-html-links.md +++ b/docs/blog/introducing-check-html-links.md @@ -1,7 +1,7 @@ --- -title: Introducing check html links - no more bad links +title: Introducing Check HTMl Links - no more bad links published: true -description: A fast link checker for static html +description: A fast link checker for static HTML tags: [html, javascript, webdev, node] cover_image: https://dev-to-uploads.s3.amazonaws.com/i/an9z6f4hdll2jlne43u3.jpg --- @@ -15,17 +15,17 @@ It's really hard to catch especially if you have a dynamic page like with WordPr Luckily, with the rise of SSG (Static Site Generators), this problem becomes easier to tackle and can be solved in large part. The reason for that is that with all HTML rendered upfront as static files we can read all of them and check every link. -## Evaluation and the decision for a new tool +## Evaluation and the Decision for a New Tool Of course, I am not the first one to come up with that idea and there are multiple tools available on the market already. -However, when checking existing solutions I found out that most of them didn't satisfy me in at least on way πŸ˜…. Things I noticed: slow to execute, deprecated, large dependency tree, confusing output for the user, ... +However, when checking existing solutions I found out that most of them didn't satisfy me in at least one way πŸ˜…. Things I noticed: slow to execute, deprecated, large dependency tree, confusing output for the user, ... Reviewing these tools I decided to create my own, with the following requirements : - Blazing fast - User-focused output - Few dependencies, to keep it lean -- Preferably in the NodeJS ecosystem +- Preferably in the Node.js ecosystem ## Focusing on Useful Output @@ -81,7 +81,7 @@ Let us turn that around and focus on missing references indeed. Here is the outp We get one 5 line error for `/speedlify/` and it tells us it's missing 495 times + 3 examples usages. Afterward, we find very clearly more missing references and where they occurred. -### A clear winner +### A Clear Winner Comparing those two outputs makes it pretty clear to me that `Missing File Focused` will make more sense if there is a chance that some links will be broken everywhere. My implementation focuses on missing links in its output. This is crucial because it allows developers to know where to focus their efforts first to get the biggest wins. @@ -113,14 +113,14 @@ Results are gatherd on January 26, 2021: | web.dev | 830 | ~3.7s | | eslint.org | 3475 | ~12.4s | -## Being part of the NodeJS ecosystem +## Being Part of the Node.js Ecosystem My daily workflow is hugely dominated by JavaScript, so it was only natural to want to stay in the same environment if I could reach my earlier requirements with it. -On top of this, the end goal is to integrate it within a bigger WIP system called [Rocket](https://github.com/modernweb-dev/rocket) which is node-based so therefore it will need to at least support NodeJS. Having it standalone (usable via `npx`) also makes it more versatile and easier to maintain/test. +On top of this, the end goal is to integrate it within a bigger WIP system called [Rocket](https://github.com/modernweb-dev/rocket) which is node-based so therefore it will need to at least support Node.js. Having it standalone (usable via `npx`) also makes it more versatile and easier to maintain/test. -## Focusing on a small Dependency Tree +## Focusing on a Small Dependency Tree -The JavaScript and NodeJs ecosystem is very active and constantly shifting. Lots of changes/improvements happen all the time. It's often hard to keep up. Therefore having a small dependency tree is something to always thrive for because it will reduce the maintenance burden down the line. And as an added benefit, it makes it smaller and easily embeddable as less stuff has to go down the wire. Lean is king πŸ‘‘. +The JavaScript and Node.js ecosystem is very active and constantly shifting. Lots of changes/improvements happen all the time. It's often hard to keep up. Therefore having a small dependency tree is something to always thrive for because it will reduce the maintenance burden down the line. And as an added benefit, it makes it smaller and easily embeddable as less stuff has to go down the wire. Lean is king πŸ‘‘. ## Solution @@ -130,23 +130,23 @@ I called it `check-html-links` and its slogan is "no more broken links or assets The features so far are: -- extracts every attribute value of id, href, src, srset -- use a wasm parser (sax-wasm) -- streams the html for performance +- extracts every attribute value of id, href, src, srcset +- use a Wasm parser (sax-wasm) +- streams the HTML for performance - check if file or id within file exist - focus on missing references/sources ## Usage -It does check your final html output so you need to execute it after your Static Site Generator. +It checks your final HTML output so you need to execute it after your Static Site Generator. ``` npx check-html-links _site ``` -## Usage Github Action +## GitHub Action Usage -[Julien](https://twitter.com/jlengrand) created a Github action available for the tool, so you can easily plug it in your existing CI. You can find it [on the GitHub Marketplace](https://github.com/marketplace/actions/check-html-links-action). +[Julien](https://twitter.com/jlengrand) created a GitHub action available for the tool, so you can easily plug it in your existing CI. You can find it [on the GitHub Marketplace](https://github.com/marketplace/actions/check-html-links-action). Here is a complete example workflow that will check the result of the folder `_site` in the root of your repository on each push: @@ -168,7 +168,7 @@ jobs: ## Comparison -Checking the output of [11ty-website](https://github.com/11ty/11ty-website) with 13 missing reference targets (used by 516 links) while checking 501 files. (on January 17, 2021) +Checking the output of the [11ty-website](https://github.com/11ty/11ty-website) with 13 missing reference targets (used by 516 links) while checking 501 files. (on January 17, 2021) | Tool | Lines printed | Duration | Lang | Dependency Tree | | ---------------- | ------------- | -------- | ---- | --------------- | @@ -193,13 +193,13 @@ Topic to work on: ## Acknowledgements -Thank you for following along on my journey on creating `check-html-links`. You can find the code on [Github](https://github.com/modernweb-dev/rocket/tree/main/packages/check-html-links). +Thank you for following along on my journey on creating `check-html-links`. You can find the code on [GitHub](https://github.com/modernweb-dev/rocket/tree/main/packages/check-html-links). Follow us on [Twitter](https://twitter.com/modern_web_dev), or follow me on my personal [Twitter](https://twitter.com/dakmor). Thanks to [Julien](https://twitter.com/jlengrand) for feedback and helping turn my scribbles to a followable story. -If you think my open source work is valuable then I would like you to check out my personal [Github Sponsor Page](https://github.com/sponsors/daKmoR). Or you can support our whole group via the [Modern Web Open Collective](https://opencollective.com/modern-web). +If you think my open source work is valuable then I would like you to check out my personal [GitHub Sponsor Page](https://github.com/sponsors/daKmoR). Or you can support our whole group via the [Modern Web Open Collective](https://opencollective.com/modern-web). --- diff --git a/docs/docs/configuration/overview.md b/docs/docs/configuration/overview.md index 6fc28cd..c5a604c 100644 --- a/docs/docs/configuration/overview.md +++ b/docs/docs/configuration/overview.md @@ -2,7 +2,7 @@ The configuration file is `rocket.config.js` or `rocket.config.mjs`. -The config files consists of the following parts: +The config files consist of the following parts: ```js import { rocketLaunch } from '@rocket/launch'; @@ -14,28 +14,28 @@ export default { }; ``` -Rocket is primarily build around plugins for each of it's systems. +Rocket is primarily build around plugins for each of its systems. New plugins can be added and all default plugins can be adjusted or even removed by using the following functions. ```js export default { - // add remark/unified plugin to the markdown processing (e.g. enable special code blocks) + // add remark/unified plugin to the Markdown processing (e.g. enable special code blocks) setupUnifiedPlugins: [], // add a rollup plugins to the web dev server (will be wrapped with @web/dev-server-rollup) AND the rollup build (e.g. enable json importing) setupDevAndBuildPlugins: [], - // add a plugin to the web dev server (will not be wrapped) (e.g. esbuild for typescript) + // add a plugin to the web dev server (will not be wrapped) (e.g. esbuild for TypeScript) setupDevPlugins: [], // add a plugin to the rollup build (e.g. optimization steps) setupBuildPlugins: [], - // add a plugin to eleventy (e.g. a filter packs) + // add a plugin to Eleventy (e.g. a filter packs) setupEleventyPlugins: [], - // add a computedConfig to eleventy (e.g. site wide default variables like socialMediaImage) + // add a computedConfig to Eleventy (e.g. site wide default variables like socialMediaImage) setupEleventyComputedConfig: [], // add a plugin to the cli (e.g. a new command like "rocket my-command") @@ -51,9 +51,9 @@ For some projects you might want to enable non-standard behaviors like importing import data from './data.json'; ``` -You can accomplish this with rollup and dev server plugins. Make sure to add both the dev-server plugin as well as the rollup plugin, so that the behaviors is the same during development as it is in the production build. +You can accomplish this with Rollup and dev server plugins. Make sure to add both the dev-server plugin as well as the Rollup plugin, so that the behaviors is the same during development as it is in the production build. -For these cases you can use `setupDevAndBuildPlugins`, which will automatically add the plugin for you to both rollup and dev-server: +For these cases you can use `setupDevAndBuildPlugins`, which will automatically add the plugin for you to both Rollup and dev-server: ```js import json from '@rollup/plugin-json'; @@ -69,8 +69,8 @@ const config = { export default config; ``` -This will add the rollup plugin `json` with the id `json` at the top of the plugin list of rollup and the dev server. It needs to be at the top so further plugins down the line can work with json imports. -For the Dev Server the plugins are automatically wrapped by `@web/dev-server-rollup`. Note that [not all rollup plugins](https://modern-web.dev/docs/dev-server/plugins/rollup/#compatibility-with-rollup-plugins) will work with the dev-server. +This will add the Rollup plugin `json` with the id `json` at the top of the plugin list of Rollup and the dev server. It needs to be at the top so further plugins down the line can work with JSON imports. +For the Dev Server the plugins are automatically wrapped by `@web/dev-server-rollup`. Note that [not all Rollup plugins](https://modern-web.dev/docs/dev-server/plugins/rollup/#compatibility-with-rollup-plugins) will work with the dev-server. ## Modifying Options of Plugins diff --git a/docs/docs/configuration/setupEleventyComputedConfig.md b/docs/docs/configuration/setupEleventyComputedConfig.md index 73adda1..2b03c72 100644 --- a/docs/docs/configuration/setupEleventyComputedConfig.md +++ b/docs/docs/configuration/setupEleventyComputedConfig.md @@ -1,12 +1,12 @@ # Configuration >> setupEleventyComputedConfig ||20 -If you want to add data that depends on other data then you can do it via [11ty's computed data](https://www.11ty.dev/docs/data-computed/). +If you want to add data that depends on other data then you can do it via [Eleventy's computed data](https://www.11ty.dev/docs/data-computed/). Rocket exposes it via `setupEleventyComputedConfig`. -## Set your own data +## Set Your Own Data -Let's say you want to add a `Welcome to the contact page` everyhwere. (a filter might be a better choise but it's a good example of the concept) +Let's say you want to add a `Welcome to the contact page` everywhere. (A filter might be a better choice, but it's a good example of the concept.) πŸ‘‰ `rocket.config.mjs` (or your theme config file) @@ -24,9 +24,9 @@ export default config; ``` {% raw %} -Now you can use everywhere {{ greeting }}. +Now you can use {{ greeting }} everywhere. {% endraw %} -And it will correctly replaced with a Welcome and the page title. +And it will be correctly replaced with a Welcome and the page title. ## Default Available Configs diff --git a/docs/docs/eleventy-plugins/mdjs-unified.md b/docs/docs/eleventy-plugins/mdjs-unified.md index bda90e4..8996b17 100644 --- a/docs/docs/eleventy-plugins/mdjs-unified.md +++ b/docs/docs/eleventy-plugins/mdjs-unified.md @@ -1,6 +1,6 @@ -# Eleventy Plugins >> Markdown JavaScript (Mdjs) +# Eleventy Plugins >> Markdown JavaScript (mdjs) -Use mdjs in your 11ty site. +Use mdjs in your Eleventy site. ## Setup @@ -8,7 +8,7 @@ Use mdjs in your 11ty site. npm install @rocket/eleventy-plugin-mdjs ``` -Create an 11ty config file `.eleventy.js` +Create an Eleventy config file `.eleventy.js` ```js const pluginMdjs = require('@rocket/eleventy-plugin-mdjs'); @@ -18,7 +18,7 @@ module.exports = function (eleventyConfig) { }; ``` -## Configure a unified or remark plugin with mdjs +## Configure a unified or remark Plugin with mdjs By providing a `setupUnifiedPlugins` function as an option to `eleventy-plugin-mdjs` you can set options for all unified/remark plugins. @@ -43,12 +43,12 @@ module.exports = function (eleventyConfig) { }; ``` -## Add a unified or remark plugin +## Add a unified or remark Plugin The order of plugins is important in unified as each plugin processes the content and passes on its result. -Some plugins do work with the markdown AST and some with the rehype (e.g. html) AST. In order to get access to the correct AST the plugin needs to be in a specific location in the processing order. +Some plugins do work with the Markdown AST and some with the rehype (e.g. HTML) AST. In order to get access to the correct AST the plugin needs to be in a specific location in the processing order. -Examples on how to insert a plugin right after creating the markdown AST. +Examples on how to insert a plugin right after creating the Markdown AST. ```js const pluginMdjs = require('@rocket/eleventy-plugin-mdjs'); diff --git a/docs/docs/markdown-javascript/overview.md b/docs/docs/markdown-javascript/overview.md index 4e212b1..2bf6de0 100644 --- a/docs/docs/markdown-javascript/overview.md +++ b/docs/docs/markdown-javascript/overview.md @@ -1,6 +1,6 @@ # Markdown JavaScript >> Overview || 10 -Markdown JavaScript (Mdjs) is a format that allows you to use JavaScript with Markdown, to create interactive demos. It does so by "annotating" JavaScript that should be executed in Markdown. +Markdown JavaScript (mdjs) is a format that allows you to use JavaScript with Markdown, to create interactive demos. It does so by "annotating" JavaScript that should be executed in Markdown. To annotate we use a code block with `js script`. @@ -13,9 +13,9 @@ To annotate we use a code block with `js script`. ## Web Components One very good use case for that can be web components. -HTML already works in markdown so all you need is to load a web components definition file. +HTML already works in Markdown so all you need is to load a web components definition file. -You could even do so within the same markdown file. +You could even do so within the same Markdown file. ````md ## This is my-card @@ -52,7 +52,7 @@ customElements.define('my-el', MyEl); ## Demo Support (Story) -mdjs comes with some additional helpers you can choose to import via +mdjs comes with some additional helpers you can choose to import: ````md ```js script @@ -61,7 +61,7 @@ import '@mdjs/mdjs-preview/mdjs-preview.js'; ``` ```` -once loaded you can use them like so. +Once loaded you can use them like so: ````md ```js script @@ -70,9 +70,7 @@ import '@mdjs/mdjs-preview/mdjs-preview.js'; ``` ```` -once loaded you can use them like so. - -### story +### Story The code snippet will actually get executed at that place and you will have a live demo @@ -88,7 +86,7 @@ export const JsStory = () => html` JS Story `; ``` ```` -#### full code support +#### Full Code Support ````md ```js story @@ -101,7 +99,7 @@ export const JsStory = () => { ``` ```` -### preview story +### Preview Story Will become a live demo wrapped in a container with a show code button. @@ -146,7 +144,7 @@ Preview your mdjs readme with live demos and auto reload. } ``` -- Create a `es-dev-server.config.js` in the root of your repo. +- Create a `es-dev-server.config.js` in the root of your repository. ```js const { mdjsTransformer } = require('@mdjs/core'); @@ -165,9 +163,9 @@ Please check out [@open-wc/demoing-storybook](https://open-wc.org/demoing/) for It includes [storybook-addon-markdown-docs](https://open-wc.org/demoing/storybook-addon-markdown-docs.html) which uses mdjs under the hood. -### Chrome Extension (currently only for Github) +### Chrome Extension (currently only for GitHub) -See live demos directly inside github page, markdown files, issues, pull requests... +See live demos directly inside GitHub pages, Markdown files, issues, pull requests... Please check out [mdjs-viewer](https://github.com/open-wc/mdjs-viewer). @@ -179,7 +177,7 @@ mdjs offers two more "basic" integrations #### `mdjsDocPage` -Creates a full blown html page by passing in the markdown. +Creates a full blown HTML page by passing in the Markdown. ```js const { mdjsDocPage } = require('@mdjs/core'); @@ -197,7 +195,7 @@ const page = await mdjsDocPage(markdownString); #### `mdjsProcess` -Pass in multiple markdown documents and you get back all the jsCode and rendered html. +Pass in multiple Markdown documents and you get back all the JavaScript code and rendered HTML. ```js const { mdjsProcess } = require('@mdjs/core'); diff --git a/docs/docs/presets/blog.md b/docs/docs/presets/blog.md index a394e83..0b672be 100644 --- a/docs/docs/presets/blog.md +++ b/docs/docs/presets/blog.md @@ -1,6 +1,6 @@ # Presets >> Blog ||30 -Enable writing blog posts within your rocket site +Enable writing blog posts within your Rocket site. ## Installation diff --git a/docs/docs/presets/launch.md b/docs/docs/presets/launch.md index c6faecc..3780d3a 100644 --- a/docs/docs/presets/launch.md +++ b/docs/docs/presets/launch.md @@ -1,6 +1,6 @@ # Presets >> Launch ||10 -Rocket comes with a preset you will love. Simple, Responsive and behaving like native it sure is going to be a hit among your users. +Rocket comes with a preset you will love. Simple, responsive and behaving like native, it sure is going to be a hit among your users. ## Installation @@ -30,7 +30,7 @@ The footer data comes from `footer.json` Notification are web components that bring in some styles. -To use them in Markdown you need to write the html tag and have it separated by an empty line. +To use them in Markdown you need to write the HTML tag and have it separated by an empty line. ```js script import '@rocket/launch/inline-notification/inline-notification.js'; @@ -62,7 +62,7 @@ I am a tip ``` -### Modify the title +### Modify the Title To override the title you can provide a property success. diff --git a/docs/docs/tools/check-html-links.md b/docs/docs/tools/check-html-links.md index 3f5a47c..bc74e3a 100644 --- a/docs/docs/tools/check-html-links.md +++ b/docs/docs/tools/check-html-links.md @@ -1,6 +1,6 @@ -# Tools >> Check Html Links ||30 +# Tools >> Check HTML Links ||30 -A fast checker for broken links/references in html. +A fast checker for broken links/references in HTML. ## Features @@ -8,7 +8,7 @@ A fast checker for broken links/references in html. - Focuses on the broken reference targets and groups references to it - Fast (can process 500-1000 documents in ~2-3 seconds) - Has only 3 dependencies (and 19 in the full tree) -- Uses [sax-wasm](https://github.com/justinwilaby/sax-wasm) for parsing streamed html +- Uses [sax-wasm](https://github.com/justinwilaby/sax-wasm) for parsing streamed HTML ## Installation @@ -26,7 +26,7 @@ npx check-html-links _site ![Test Run Screenshot](./images/check-html-links-screenshot.png) -## Comparision +## Comparison Checking the output of [11ty-website](https://github.com/11ty/11ty-website) with 13 missing reference targets (used by 516 links) while checking 501 files. (on January 17, 2021) diff --git a/docs/docs/tools/plugins-manager.md b/docs/docs/tools/plugins-manager.md index da208e5..c7440e7 100644 --- a/docs/docs/tools/plugins-manager.md +++ b/docs/docs/tools/plugins-manager.md @@ -34,7 +34,7 @@ var processor = unified().use(markdown).use(toc, { maxDepth: 2 }); // ... ``` -## Problem statement +## Problem Statement > Executing or adding a plugin in a special way is a one time process. You can not transparently later change the options of the given plugin. @@ -42,7 +42,7 @@ This means if you wish to define default plugins and allow your user to override ## Solution -The plugins manager let's you orchestrate a set of "meta plugins" which are defined by +The plugins manager lets you orchestrate a set of "meta plugins" which are defined by - name - plugin @@ -193,7 +193,7 @@ adjustPluginOptions('json', false); // resulting options = false ``` -## Converting metaPlugins to an actual plugin +## Converting metaPlugins to an Actual Plugin To execute all setup function you can use this little helper diff --git a/docs/docs/tools/rollup-config.md b/docs/docs/tools/rollup-config.md index f638830..42ab9ce 100644 --- a/docs/docs/tools/rollup-config.md +++ b/docs/docs/tools/rollup-config.md @@ -1,15 +1,15 @@ # Tools >> Rollup Config ||20 Rollup configuration to help you get started building modern web applications. -You write modern javascript using the latest browser-features, rollup will optimize your code for production and ensure it runs on all supported browsers. +You write modern JavaScript using the latest browser features. Rollup will optimize your code for production and ensure it runs on all supported browsers. ## Features -- Set HTML or JS as input and/or output +- Set HTML or JavaScript as input and/or output - Optimized for browsers which support modules - Loads polyfills using feature detection - Generates a service worker -- Minifies JS +- Minifies JavaScript - Minifies lit-html templates ## Setup @@ -25,7 +25,7 @@ You write modern javascript using the latest browser-features, rollup will optim ```js import { createSpaConfig } from '@rocket/building-rollup'; // use `import { createBasicConfig }` to do regular JS to JS bundling - // use `import { createMpaConfig }` to bundle multiple html files + // use `import { createMpaConfig }` to bundle multiple HTML files export default createSpaConfig({ input: 'index.html', @@ -54,7 +54,7 @@ Our config sets you up with good defaults for most projects. Additionally you ca We use the [plugins-manager](./plugins-manager.md) for it. -### Customizing the babel config +### Customizing the Babel Config You can define custom babel plugins to be loaded by adding a `.babelrc` or `babel.config.js` to your project. See [babeljs config](https://babeljs.io/docs/en/configuration) for more information. @@ -66,9 +66,9 @@ For example to add support for class properties: } ``` -### Customizing default plugins +### Customizing Default Plugins -Our config creators install a number of rollup plugins by default: +Our config creators install a number of Rollup plugins by default: Basic, SPA and MPA plugins: diff --git a/docs/guides/configuration/getting-started.md b/docs/guides/configuration/getting-started.md index 11fd7e2..0d28fa0 100644 --- a/docs/guides/configuration/getting-started.md +++ b/docs/guides/configuration/getting-started.md @@ -16,11 +16,11 @@ export default /** @type {Partial} */ ({ }); ``` -The Plugins Manager helps you register and execute your plugins across the various Rocket components - rollup, dev-server, eleventy, and markdown. It replaces the specific registration/execution call in a given plugin system by an intent to use that plugin. +The Plugins Manager helps you register and execute your plugins across the various Rocket components - Rollup, Web Dev Server, Eleventy, and Markdown. It replaces the specific registration/execution call in a given plugin system by an intent to use that plugin. ## Adding Remark/Unified Plugins -If you want to a plugin to the markdown processing you can use `setupUnifiedPlugins`. +If you want to a plugin to the Markdown processing you can use `setupUnifiedPlugins`. ```js import emoji from 'remark-emoji'; @@ -34,5 +34,5 @@ const config = { export default config; ``` -For plugins that should handle the markdown AST you should use `addPlugin({ location: 'markdown', name: 'my-plugin', plugin: MyPlugin})`.
-While for the rehype ast you should use `addPlugin({ location: 'remark2rehype', name: 'my-plugin', plugin: MyPlugin})`. +For plugins that should handle the Markdown AST you should use `addPlugin({ location: 'markdown', name: 'my-plugin', plugin: MyPlugin})`.
+While for the rehype AST you should use `addPlugin({ location: 'remark2rehype', name: 'my-plugin', plugin: MyPlugin})`. diff --git a/docs/guides/first-pages/adding-pages.md b/docs/guides/first-pages/adding-pages.md index 1ac8235..b14a954 100644 --- a/docs/guides/first-pages/adding-pages.md +++ b/docs/guides/first-pages/adding-pages.md @@ -8,9 +8,9 @@ It can help to examine each new page and menu carefully, to come to terms with t -## Add a section +## Add a Section -In most cases you will have multiple sections in your website and each of those sections will come with it's own sidebar navigation. +In most cases you will have multiple sections in your website and each of those sections will come with its own sidebar navigation. To create a section you need to create a folder with an `index.md`. @@ -38,7 +38,7 @@ Don't worry if this isn't how you would have styled or placed your menu bar or s It might be more practical to stay below 5 sections. -## Adding a category +## Adding a Category Often each section will have multiple categories. @@ -54,7 +54,7 @@ mkdir docs/guides/first-pages/ # First Pages ``` -## Adding a page to a category +## Adding a Page to a Category πŸ‘‰ `docs/guides/first-pages/getting-started.md` @@ -64,14 +64,14 @@ mkdir docs/guides/first-pages/ This is how you get started. ``` -## Headings as anchor and menu items +## Headings as Anchor and Menu Items _**Within**_ any page, you can still add links to your navigation! -Note that md text prefixed with one or two # signs also becomes and anchor in the page and a link in the sidebar navigation when the page is open. +Note that Markdown text prefixed with one or two # signs also becomes an anchor in the page and a link in the sidebar navigation when the page is open. ```md -## Headings as anchor and menu items +## Headings as Anchor and Menu Items _**Within**_ any page, you can still add links to your navigation! ``` @@ -80,6 +80,6 @@ _**Within**_ any page, you can still add links to your navigation! import '@rocket/launch/inline-notification/inline-notification.js'; ``` -## Example as a reference +## Example as a Reference If implicit navigation, derived from content, is a bit too much to grasp in one sitting, feel free to examine the **docs** folder in [the rocket codebase behind the pages you are reading](https://github.com/modernweb-dev/rocket) for more examples. diff --git a/docs/guides/first-pages/getting-started.md b/docs/guides/first-pages/getting-started.md index ad908fa..a39cb0f 100644 --- a/docs/guides/first-pages/getting-started.md +++ b/docs/guides/first-pages/getting-started.md @@ -1,6 +1,6 @@ # First Pages >> Getting Started ||10 -Rocket is has the following prerequisits: +Rocket has the following prerequisites: - [Node 14+](https://nodejs.org/en/) @@ -37,7 +37,7 @@ The fastest way to get started is by using an existing preset like the launch pr You may be tempted to skip the step above, because you're not ready to commit to git yet! -Rocket uses the .gitignore file to manage it's requirements. If you skip this step, rocket will fail to deploy! +Rocket uses the .gitignore file to manage its requirements. If you skip this step, Rocket will fail to deploy! @@ -62,25 +62,25 @@ Rocket uses the .gitignore file to manage it's requirements. If you skip this st -All further pathes are relative to your project root (my-project in this case) +All further paths are relative to your project root (my-project in this case). -## Add your first page +## Add your First Page πŸ‘‰ `docs/index.md` ```md -# Welcome to your Rocket site +# Welcome to Your Rocket Site -Text here, like any markdown file. +Text here, like any Markdown file. ``` This tutorial assumes you are familiar with Markdown, for page authoring. Please note that the heading - text prefixed with `#` or `##` - is not optional for each page in this tutorial. Everything below that first line is optional Markdown text. -## Start up: +## Startup: πŸ‘‰ `package.json` diff --git a/docs/guides/first-pages/link-to-other-pages.md b/docs/guides/first-pages/link-to-other-pages.md index e6ca1c2..744be97 100644 --- a/docs/guides/first-pages/link-to-other-pages.md +++ b/docs/guides/first-pages/link-to-other-pages.md @@ -1,6 +1,6 @@ # First Pages >> Linking ||20 -Standard markdown applies and you can link via +Standard Markdown applies. You can link like this: ```md [visible label](./path/to/other-file.md) diff --git a/docs/guides/first-pages/manage-sidebar.md b/docs/guides/first-pages/manage-sidebar.md index a68c6e3..e2a406b 100644 --- a/docs/guides/first-pages/manage-sidebar.md +++ b/docs/guides/first-pages/manage-sidebar.md @@ -21,7 +21,7 @@ Will be ordered as `First`, `Second`, ## How it works -Internally `# Foo >> Bar >> Baz ||20` get's converted to. +Internally `# Foo >> Bar >> Baz ||20` gets converted to. ``` --- diff --git a/docs/guides/first-pages/urls.md b/docs/guides/first-pages/urls.md index b9265e4..82ba668 100644 --- a/docs/guides/first-pages/urls.md +++ b/docs/guides/first-pages/urls.md @@ -1,5 +1,5 @@ -# First Pages >> Urls ||100 +# First Pages >> URLs ||100 -Urls will be represented by the folder structure... +URLs will be represented by the folder structure. -You can use a frontmatter with permalink to override +You can use front matter with a [permalink](https://www.11ty.dev/docs/permalinks/) to override. diff --git a/docs/guides/first-pages/use-javascript.md b/docs/guides/first-pages/use-javascript.md index 349581b..b61473f 100644 --- a/docs/guides/first-pages/use-javascript.md +++ b/docs/guides/first-pages/use-javascript.md @@ -1,6 +1,6 @@ # First Pages >> Use JavaScript ||40 -You can use `js script` to execute javascript (type = module) +You can use `js script` to execute JavaScript (`type="module"`). ```` ```js script @@ -8,7 +8,7 @@ console.log('foo'); ``` ```` -This can be useful for importing web components and using them in markdown +This can be useful for importing web components and using them in Markdown. ```` ```js script @@ -16,7 +16,7 @@ import 'magic-reveal/magic-reveal.js'; -This text will get magically revealed. I can **still** use markdown as long as between the opening/closing tag there is an empty line. +This text will get magically revealed. I can **still** use Markdown as long as there is an empty line between the opening/closing tags and my text. ``` diff --git a/docs/guides/go-live/overview.md b/docs/guides/go-live/overview.md index e10675f..ed7e713 100644 --- a/docs/guides/go-live/overview.md +++ b/docs/guides/go-live/overview.md @@ -2,14 +2,14 @@ A few things are usually needed before going live "for real". -## Add a not found page +## Add a Not Found Page -When a user enters a url that does not exists then a "famous" 404 page not found error occures. +When a user enters a URL that does not exist, a "famous" 404 Page Not Found error occurs. Many servers are configured to handle this automatically and to serve a 404.html page instead. -The [Rocket Lauch Preset](../../docs/presets/launch.md) ships a default 404 template you can use. +The [Rocket Launch preset](../../docs/presets/launch.md) ships a default 404 template you can use. -To enable it you need to creating a 404.md and use the 404 layout. +To enable it, you need to create a 404.md and use the 404 layout. πŸ‘‰ `docs/404.md` @@ -20,11 +20,11 @@ permalink: 404.html --- ``` -## Add a sitemap +## Add a Sitemap A sitemap can be used to inform search engines or services about the pages your site has. -You can create one by adding this file +You can create one by adding this file: πŸ‘‰ `docs/sitemap.njk` diff --git a/docs/guides/go-live/social-media.md b/docs/guides/go-live/social-media.md index ebd89c3..3006df6 100644 --- a/docs/guides/go-live/social-media.md +++ b/docs/guides/go-live/social-media.md @@ -3,15 +3,15 @@ Having a nice preview image for social media can be very helpful. For that reason Rocket creates those automatically with the title, parent title, section and your logo. -It will look like this but with your logo +It will look like this but with your logo: Social Media Image of this page There are multiple ways you can modify it. -Note: If your logo has an `` tag it will throw an error as it will be inlined into this svg and nested xml tags are not allowed. +Note: If your logo has an `` tag it will throw an error as it will be inlined into this SVG and nested XML tags are not allowed. -## Setting it via frontMatter +## Setting it via Front Matter You can create your own image and link it with something like this @@ -21,7 +21,7 @@ socialMediaImage: path/to/my/image.png --- ``` -## Providing your own text +## Providing Your Own Text Sometimes extracting the title + title of parent is not enough but you still want to use the "default image". @@ -47,10 +47,10 @@ module.exports = async function () { }; ``` -## Override the default image +## Override the Default Image Often you want to have a unique style for your social media images. -For that you can provide your own function which returns a string of an svg to render the image. +For that you can provide your own function which returns a string of an SVG to render the image. πŸ‘‰ `rocket.config.mjs` @@ -100,9 +100,9 @@ const config = { export default config; ``` -## Using an svg file as a src with nunjucks +## Using an SVG File as a src with Nunjucks -If you have multiple variations it may be easier to save them as svg files and using a template system +If you have multiple variations it may be easier to save them as SVG files and use a template system. WARNING: Untested example diff --git a/docs/guides/presets/create-your-own.md b/docs/guides/presets/create-your-own.md index 78cbf92..5b96654 100644 --- a/docs/guides/presets/create-your-own.md +++ b/docs/guides/presets/create-your-own.md @@ -1,6 +1,6 @@ # Presets >> Create your own || 90 -A preset is setup function and a folder including `_assets`, `_data` and `_includes` (all optional). +A preset is a setup function and a folder including `_assets`, `_data` and `_includes` (all optional). To play around with a preset you can create a folder `fire-theme`. @@ -35,7 +35,7 @@ body { } ``` -Once you have that you can add it to your Rocket Config. +Once you have that you can add it to your Rocket config. NOTE: The order of presets is important, as for example in this case we take everything from `rocketLaunch` but later override via `fireTheme`. @@ -50,7 +50,7 @@ export default { }; ``` -## Publish a preset +## Publish a Preset If you would like to publish a preset to use it on multiple websites or share it with your friends you can do like so. diff --git a/docs/guides/presets/using-templates.md b/docs/guides/presets/using-templates.md index 3d4e6e3..7bb5029 100644 --- a/docs/guides/presets/using-templates.md +++ b/docs/guides/presets/using-templates.md @@ -1,3 +1,3 @@ # Presets >> Using templates ||30 -Most presetse have specific entry files you can override... +Most presets have specific entry files you can override... diff --git a/docs/index.md b/docs/index.md index 803f949..dfed2d8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,11 +12,11 @@ reasons: - header: Small text: No overblown tools or frontend frameworks, add JavaScript and/or Web Components only on pages where needed. - header: Pre-Rendered - text: Statically generated content means less javascript to ship and process. + text: Statically generated content means less JavaScript to ship and process. - header: Zero Configuration - text: Automatic code splitting, filesystem based routing, and javascript in markdown. + text: Automatic code splitting, filesystem based routing, and JavaScript in Markdown. - header: Meta Framework - text: 'Build on top of giants like eleventy, Rollup, and Modern Web.' + text: 'Build on top of giants like Eleventy, Rollup, and Modern Web.' - header: Powerful Default Template text: Provide content and you are ready to go. - header: Ready for Production diff --git a/packages/blog/README.md b/packages/blog/README.md index 27b92a8..bf6080c 100644 --- a/packages/blog/README.md +++ b/packages/blog/README.md @@ -1,5 +1,5 @@ # Blog Preset for Rocket -Add blog posts to your rocket site. +Add blog posts to your Rocket site. For docs please see our homepage [https://rocket.modern-web.dev/docs/presets/blog/](https://rocket.modern-web.dev/docs/presets/blog/). diff --git a/packages/building-rollup/README.md b/packages/building-rollup/README.md index 520d7e6..dc42798 100644 --- a/packages/building-rollup/README.md +++ b/packages/building-rollup/README.md @@ -1,6 +1,6 @@ # Building Rollup Rollup configuration to help you get started building modern web applications. -You write modern javascript using the latest browser-features, rollup will optimize your code for production and ensure it runs on all supported browsers. +You write modern JavaScript using the latest browser features. Rollup will optimize your code for production and ensure it runs on all supported browsers. For docs please see our homepage [https://rocket.modern-web.dev/docs/building/rollup-config/](https://rocket.modern-web.dev/docs/building/rollup-config/). diff --git a/packages/building-rollup/demo/js/demo-app.js b/packages/building-rollup/demo/js/demo-app.js index de4aa9a..82b0a0c 100644 --- a/packages/building-rollup/demo/js/demo-app.js +++ b/packages/building-rollup/demo/js/demo-app.js @@ -2,7 +2,7 @@ import { LitElement, html, css } from 'lit-element'; import './demo-component.js'; -// partial css trips up the minifier +// partial CSS trips up the minifier const fontSize = css` 16 `; diff --git a/packages/building-rollup/demo/ts/demo-app.ts b/packages/building-rollup/demo/ts/demo-app.ts index 7822c86..ae5ff93 100644 --- a/packages/building-rollup/demo/ts/demo-app.ts +++ b/packages/building-rollup/demo/ts/demo-app.ts @@ -1,6 +1,6 @@ import { LitElement, html, customElement } from 'lit-element'; -const msg: string = 'Typescript demo works'; +const msg: string = 'TypeScript demo works'; @customElement('demo-app') class DemoApp extends LitElement { diff --git a/packages/building-rollup/test-node/createMpaConfig.test.js b/packages/building-rollup/test-node/createMpaConfig.test.js index 9097ba2..16dd3ea 100644 --- a/packages/building-rollup/test-node/createMpaConfig.test.js +++ b/packages/building-rollup/test-node/createMpaConfig.test.js @@ -59,13 +59,13 @@ describe('createMapConfig', () => { stripToBody: true, stripServiceWorker: true, }); - expect(indexHtml).to.equal('

Only static html content in index.html

'); + expect(indexHtml).to.equal('

Only static HTML content in index.html

'); const subHtmlIndexHtml = await readOutput('sub-html/index.html', { stripToBody: true, stripServiceWorker: true, }); - expect(subHtmlIndexHtml).to.equal('

Only static html content in sub-html/index.html

'); + expect(subHtmlIndexHtml).to.equal('

Only static HTML content in sub-html/index.html

'); const subJsIndexHtml = await readOutput('sub-js/index.html', { stripToBody: true, diff --git a/packages/building-rollup/test-node/fixtures/mpa/index.html b/packages/building-rollup/test-node/fixtures/mpa/index.html index 2e4b4d3..a21bed7 100644 --- a/packages/building-rollup/test-node/fixtures/mpa/index.html +++ b/packages/building-rollup/test-node/fixtures/mpa/index.html @@ -1 +1 @@ -

Only static html content in index.html

+

Only static HTML content in index.html

diff --git a/packages/building-rollup/test-node/fixtures/mpa/sub-html/index.html b/packages/building-rollup/test-node/fixtures/mpa/sub-html/index.html index 1a8c6f8..0bcdb7b 100644 --- a/packages/building-rollup/test-node/fixtures/mpa/sub-html/index.html +++ b/packages/building-rollup/test-node/fixtures/mpa/sub-html/index.html @@ -1 +1 @@ -

Only static html content in sub-html/index.html

+

Only static HTML content in sub-html/index.html

diff --git a/packages/check-html-links/README.md b/packages/check-html-links/README.md index 3d2d529..73a74e7 100644 --- a/packages/check-html-links/README.md +++ b/packages/check-html-links/README.md @@ -1,6 +1,6 @@ -# Check Html Links +# Check HTML Links -A fast checker for broken links/references in html. +A fast checker for broken links/references in HTML. ## Installation @@ -18,7 +18,7 @@ For docs please see our homepage [https://rocket.modern-web.dev/docs/tools/check ## Comparison -Checking the output of [11ty-website](https://github.com/11ty/11ty-website) with 13 missing reference targets (used by 516 links) while checking 501 files. (on January 17, 2021) +Checking the output of the [11ty-website](https://github.com/11ty/11ty-website) with 13 missing reference targets (used by 516 links) while checking 501 files. (on January 17, 2021) | Tool | Lines printed | Times | Lang | Dependency Tree | | ---------------- | ------------- | ------ | ---- | --------------- | diff --git a/packages/cli/README.md b/packages/cli/README.md index 01ac1b6..26eb8b4 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,5 +1,5 @@ -# Rocket Cli +# Rocket CLI -Execute Rocket within you CLI +Execute Rocket within your CLI. For docs please see our homepage [https://rocket.modern-web.dev/](https://rocket.modern-web.dev/). diff --git a/packages/cli/demo/docs/blog/introducing-mdjs.md b/packages/cli/demo/docs/blog/introducing-mdjs.md index 8a2b76c..be75983 100644 --- a/packages/cli/demo/docs/blog/introducing-mdjs.md +++ b/packages/cli/demo/docs/blog/introducing-mdjs.md @@ -13,21 +13,21 @@ Users should at least be able to get a high level understanding of what they are On the web, we have many many different ways of writing documentation. However, one thing almost all of them have in common is that they rely on [Markdown](https://en.wikipedia.org/wiki/Markdown) or some kind of variation of it. -And it's no surprise, because Markdown is supported practically everywhere (vscode, atom, github, gitlab, dev.to, npmjs, ...) +And it's no surprise, because Markdown is supported practically everywhere (VS Code, Atom, GitHub, GitLab, dev.to, npmjs, ...) -## For tools that do not run in the browser +## For Tools that Do Not Run in the Browser In this case, you will mostly share code snippets that people will need to run in their own projects in which case traditional static site generators like [Docusaurus](https://docusaurus.io/), [VuePress](https://vuepress.vuejs.org/), [Gatsby](https://www.gatsbyjs.org/), et al work great. All of them have full support for Markdown and allow you to easily create beautiful documentation pages with code snippets/highlighting, and more. And frankly, if that is your use case almost everything you need should be possible with those tools as long as you feel comfortable with the ecosystem/framework. -## For (visual) components that do run in the browser +## For (Visual) Components that Do Run in the Browser In this context, users probably do expect a live demo to see all the different options of your component in action. So pure Markdown is usually not enough as we now want to actually execute code and "insert" our working component in our documentation somehow. This would require specialized handling for each framework. ### Vue -For Vue, as an example, you can use VuePress which auto registers all Vue components in a certain folder and then you can use as normal html tags since Markdown supports html +For Vue, as an example, you can use VuePress which auto registers all Vue components in a certain folder and then you can use as normal HTML tags since Markdown supports HTML ``` . @@ -40,17 +40,17 @@ For Vue, as an example, you can use VuePress which auto registers all Vue compon ``` -- supports vue components and has "magical" import for them -- no support for generic javascript or passing properties to components +- supports Vue components and has "magical" import for them +- no support for generic JavaScript or passing properties to components ### React -For React you can use [Mdx](https://mdxjs.com/) which extends Markdown with JSX support. Mdx is available via multiple tools like [Gatsby](https://www.gatsbyjs.org/), [docz](https://www.docz.site/), [storybook](https://storybook.js.org/), etc. +For React you can use [MDX](https://mdxjs.com/) which extends Markdown with JSX support. MDX is available via multiple tools like [Gatsby](https://www.gatsbyjs.org/), [docz](https://www.docz.site/), [storybook](https://storybook.js.org/), etc. ```md import { Chart } from '../components/chart' -# Here’s a chart +# Here’s a Chart The chart is rendered inside our MDX document. @@ -58,7 +58,7 @@ The chart is rendered inside our MDX document. - supports import/export JavaScript - passes everything through JSX -- Doesn't look _great_ on github, requires special tools in editors to get highlighting +- doesn't look _great_ on GitHub, requires special tools in editors to get highlighting ## Limitations @@ -71,7 +71,7 @@ The primary goals are - minimal complexity - follows progressive enhancement -- stick close to valid markdown syntax +- stick close to valid Markdown syntax - code highlighting in editors without additional tools - looks good on github/gitlab/any source code management tool @@ -91,8 +91,8 @@ Alright, enough talk, you can see it live here: **How does it work** -Mdjs hooks into [remark](https://remark.js.org/) and extracts all those tagged js blocks. -In the end, html and js is separately available. +mdjs hooks into [remark](https://remark.js.org/) and extracts all those tagged JavaScript blocks. +In the end, HTML and JS are separately available. ```js { @@ -105,9 +105,9 @@ It can then be combined/processed by any tool to create an actual documentation The process looks like this: -1. Extract `js script` and separate it from md -2. Render md -3. Provide html & js +1. Extract `js script` and separate it from Markdown +2. Render Markdown +3. Provide HTML & JS ![mdjs script transform](https://raw.githubusercontent.com/open-wc/blog-posts/master/2020-04-introducing-mdjs-interactive-demos-everywhere/images/mdjs-script-transform-resized.gif) @@ -115,11 +115,11 @@ The process looks like this: This already is powerful enough to directly include JavaScript and render web components with attributes. -## Enhancing mdjs with demo format +## Enhancing mdjs with Demo Format Now that we can execute JavaScript within our Markdown this opens the door for more advanced features. -Our first step is to create another enhanced js code block, namely; `js story`. +Our first step is to create another enhanced JS code block, namely; `js story`. From this code block you can export a function to be executed on demand: ```js script @@ -150,13 +150,13 @@ Under the hood, this adds an extra step to the processing: 1. Extract `js script` and separate from md 2. Extract `js story` and `js preview-story` and separate from md -3. Put a placeholder `` or `mdjs-preview` at it's place -4. Render markdown -5. Provide html, javascript, and stories +3. Put a placeholder `` or `mdjs-preview` at its place +4. Render Markdown +5. Provide HTML, JavaScript, and stories -This is all the information we need to create full javascript and demo capable pages purely from markdown. +This is all the information we need to create full JavaScript and demo capable pages purely from Markdown. -By default Mdjs takes it a small step further by supporting an actual template system - namely [lit-html](https://lit-html.polymer-project.org/). +By default mdjs takes it a small step further by supporting an actual template system - namely [lit-html](https://lit-html.polymer-project.org/). ```js script import './demo-wc-card.js'; @@ -177,7 +177,7 @@ Here another playground mimicking a full documentation page. [==> Link to editable demo <==](https://webcomponents.dev/edit/PqrQkg3abvFJ7vxyZuqa?pm=1&sv=1) -## mdjs default docs page +## mdjs Default Docs Page Once all this meta-information is available you can render a specific docs page. @@ -194,11 +194,11 @@ for (const story of stories) { All of this happens under the hood for you πŸ€— -## Where can you use mdjs? +## Where Can You Use mdjs? -### You can use it locally via es-dev-server +### Locally with ES Dev Server -Here i'll show you how you can create a github like markdown view for all your local markdown files including live demos. +Here I'll show you how you can create a GitHub-like Markdown view for all your local Markdown files including live demos. ![es-dev-server screenshot](https://raw.githubusercontent.com/open-wc/blog-posts/master/2020-04-introducing-mdjs-interactive-demos-everywhere/images/es-dev-server-screenshot.png) @@ -212,7 +212,7 @@ Here i'll show you how you can create a github like markdown view for all your l } ``` -- Create a `es-dev-server.config.js` in the root of your repo. +- Create a `es-dev-server.config.js` in the root of your repository. ```js const { mdjsTransformer } = require('@mdjs/core'); @@ -227,9 +227,9 @@ Here i'll show you how you can create a github like markdown view for all your l After executing `npm run start` you can happily browse your live documentation via [http://localhost:8000/README.md](http://localhost:8000/README.md). -You can see an example setup in the [demo-wc-card repo](https://github.com/daKmoR/demo-wc-card). +You can see an example setup in the [demo-wc-card repository](https://github.com/daKmoR/demo-wc-card). -### You can use it via Storybook +### Storybook If you want to work on individual components or get a list of all demos you can use Storybook. @@ -245,7 +245,7 @@ If you want to work on individual components or get a list of all demos you can } ``` -- Adjust your `.storybook/main.js` to load markdown files +- Adjust your `.storybook/main.js` to load Markdown files ```js module.exports = { @@ -258,7 +258,7 @@ If you want to work on individual components or get a list of all demos you can }; ``` -- Add to every markdown file that should be in storybook a name via +- Add to every Markdown file that should be in storybook a name via ```js export default { @@ -267,13 +267,13 @@ If you want to work on individual components or get a list of all demos you can ``` And just like that, you are good to go. -No additional changes to any files are needed; a plugin will take care of everything by converting your markdown files to the support Storybook's mdx format. +No additional changes to any files are needed; a plugin will take care of everything by converting your Markdown files to the support Storybook's MDX format. For more detailed information please see [https://open-wc.org/demoing-storybook/](https://open-wc.org/demoing-storybook/). -### Show it on github +### GitHub -Since Github supports markdown out of the box, we can take things even further by using Mdjs. +Since GitHub supports Markdown out of the box, we can take things even further by using mdjs. ![github screenshot](https://raw.githubusercontent.com/open-wc/blog-posts/master/2020-04-introducing-mdjs-interactive-demos-everywhere/images/github-screenshot.png) @@ -283,23 +283,23 @@ As it's not supported by github directly you will need a chrome extension called - Do you want to show a live example of the issue you are having? mdjs-viewer! Almost looks like black magic, huh? -All you did was install a Chrome extension and suddenly Github got superpowers. +All you did was install a Chrome extension and suddenly GitHub got superpowers. All that you need is to have some Markdown files with the correct code fence blocks, and have your code up and running on [unpkg.com](https://unpkg.com). **How does it actually work?** -The extension detects which Github page you are on. -If it actually finds a markdown file or an issue with mdjs code then it adds a "show demo" button to activate it. +The extension detects which GitHub page you are on. +If it actually finds a Markdown file or an issue with mdjs code then it adds a "show demo" button to activate it. Only if you click the button it will start gathering all the needed info. - find the nearest `package.json` -- read the actual markdown file/issue content +- read the actual Markdown file/issue content - replace all bare import with `unpkg.com` imports - replace all relative imports with `unpkg.com` and the name of the package.json + relative path for it - create a secured iframe - position the iframe absolute as an overlays -- put the javascript and html code inside the iframe +- put the JavaScript and HTML code inside the iframe - the button becomes a toggle to show/hide the iframe Some of the tasks are more complicated and require some extra work to make it secure but in essence, that's it. @@ -312,7 +312,7 @@ Especially as the readme and issue content still remain useful even without the For more detailed information please see [https://github.com/open-wc/mdjs-viewer](https://github.com/open-wc/mdjs-viewer). -### Supported on webcomponents.dev +### webcomponents.dev Fully supported by this awesome online editor. @@ -330,7 +330,7 @@ All the demo links are actually from [webcomponents.dev](https://webcomponents.d Be sure to [check it out](https://webcomponents.dev/). -## How you can add support for mdjs +## How You Can Add Support for mdjs Please check the official documentation page at [https://open-wc.org/mdjs/](https://open-wc.org/mdjs/). @@ -344,7 +344,7 @@ Now go out there and write good documentation for your components! ## Future -- Have a separate github repo (potentially group as well). +- Have a separate GitHub repository (potentially group as well). - Have a dedicated homepage - The default story preview frame should look a little nicer - Support multiple renderers - discussion in [issue](https://github.com/open-wc/open-wc/issues/1498) diff --git a/packages/cli/demo/docs/docs/modern-web.md b/packages/cli/demo/docs/docs/modern-web.md index f857cc8..511a1ed 100644 --- a/packages/cli/demo/docs/docs/modern-web.md +++ b/packages/cli/demo/docs/docs/modern-web.md @@ -15,8 +15,8 @@ eleventyNavigation: | /learn/codelabs/ | - Codelabs Overview | | /learn/codelabs/x/ | ??? | | /learn/fundaments/ | - Fundaments | -| /learn/fundaments/html/ | -- html | -| /learn/fundaments/css/ | -- css Basics | +| /learn/fundaments/html/ | -- HTML | +| /learn/fundaments/css/ | -- CSS Basics | | /learn/fundaments/browser/ | -- Browser Basics | | /learn/fundaments/specs/ | -- Specs Basics | | /learn/fundaments/server/ | -- Web Server Basics | @@ -36,8 +36,8 @@ eleventyNavigation: | /docs/build/rollup-plugin-html | -- Rollup Plugin for html | | /docs/build/rollup-plugin-polyfills-loader | -- Rollup Plugin for html | | /docs/build/polyfills-loader | -- Polyfills loading system | -| /docs/mdjs?docs?/ | - Mdjs/Docs Overview | -| /docs/mdjs/elements | - Mdjs Overview | +| /docs/mdjs?docs?/ | - mdjs/Docs Overview | +| /docs/mdjs/elements | - mdjs Overview | | - | - | | **/blog/** | **Blog Overview** | | /blog/2020/08/01/announcing-modern-web | - Announcement Blog Post | diff --git a/packages/cli/demo/docs/index.md b/packages/cli/demo/docs/index.md index 4276421..4dea5ad 100644 --- a/packages/cli/demo/docs/index.md +++ b/packages/cli/demo/docs/index.md @@ -14,15 +14,15 @@ The modern web setup with less complexity ### Small -No overblown tools and frontend frameworks. +No overblown tools and front-end frameworks. ### Fast -By shipping html +By shipping HTML ### Simple -Pure html with little js helpers here and there allows you to debug and enhance where needed. +Pure HTML with little JavaScript helpers here and there allows you to debug and enhance where needed. ### Meta Framework diff --git a/packages/cli/demo/docs/learn/codelabs/web-components-basics/01-custom-elements.md b/packages/cli/demo/docs/learn/codelabs/web-components-basics/01-custom-elements.md index dedfeb2..f324e07 100644 --- a/packages/cli/demo/docs/learn/codelabs/web-components-basics/01-custom-elements.md +++ b/packages/cli/demo/docs/learn/codelabs/web-components-basics/01-custom-elements.md @@ -17,7 +17,7 @@ Modify your HTML to wrap the "Hello world" message in an element called `` tag. When the browser encounters an unknown HTML tag like ``, it will just render it as an inline element and move on. With the custom elements API, we can tell the browser what to do with the HTML tag that we have just created. -We need to do this in javascript, so let's add a script tag to the bottom of our `` element: +We need to do this in JavaScript, so let's add a script tag to the bottom of our `` element: ```html