mirror of
https://github.com/modernweb-dev/rocket.git
synced 2026-04-11 15:54:31 +00:00
Compare commits
1 Commits
feat/engin
...
fix/checkL
| Author | SHA1 | Date | |
|---|---|---|---|
|
31eca9f63c |
@@ -10,5 +10,3 @@ _site
|
||||
_site-dev
|
||||
__output
|
||||
__output-dev
|
||||
|
||||
docs/_merged*
|
||||
|
||||
6
.gitignore
vendored
6
.gitignore
vendored
@@ -1,5 +1,6 @@
|
||||
## editors
|
||||
/.idea
|
||||
/.vscode
|
||||
|
||||
## system files
|
||||
.DS_Store
|
||||
@@ -27,7 +28,9 @@ stats.html
|
||||
*.tsbuildinfo
|
||||
|
||||
## Rocket ignore files (need to be the full relative path to the folders)
|
||||
*-mdjs-generated.js
|
||||
docs/_merged_data/
|
||||
docs/_merged_assets/
|
||||
docs/_merged_includes/
|
||||
_site
|
||||
_site-dev
|
||||
|
||||
@@ -37,4 +40,3 @@ _merged_assets
|
||||
_merged_includes
|
||||
__output
|
||||
__output-dev
|
||||
docs_backup
|
||||
|
||||
7
.vscode/extensions.json
vendored
7
.vscode/extensions.json
vendored
@@ -1,7 +0,0 @@
|
||||
{
|
||||
// See http://go.microsoft.com/fwlink/?LinkId=827846
|
||||
// for the documentation about the extensions.json format
|
||||
"recommendations": [
|
||||
"dbaeumer.vscode-eslint"
|
||||
]
|
||||
}
|
||||
34
.vscode/launch.json
vendored
34
.vscode/launch.json
vendored
@@ -1,34 +0,0 @@
|
||||
// A launch configuration that compiles the extension and then opens it inside a new window
|
||||
// Use IntelliSense to learn about possible attributes.
|
||||
// Hover to view descriptions of existing attributes.
|
||||
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Run Web Dev Server Extension",
|
||||
"type": "extensionHost",
|
||||
"request": "launch",
|
||||
"args": [
|
||||
"--extensionDevelopmentPath=${workspaceFolder}/packages/vscode-rocket"
|
||||
],
|
||||
"outFiles": [
|
||||
"${workspaceFolder}/packages/vscode-rocket/out/**/*.js"
|
||||
],
|
||||
"preLaunchTask": "Compile vscode-rocket"
|
||||
},
|
||||
{
|
||||
"name": "Extension Tests",
|
||||
"type": "extensionHost",
|
||||
"request": "launch",
|
||||
"args": [
|
||||
"--extensionDevelopmentPath=${workspaceFolder}",
|
||||
"--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
|
||||
],
|
||||
"outFiles": [
|
||||
"${workspaceFolder}/out/test/**/*.js"
|
||||
],
|
||||
"preLaunchTask": "${defaultBuildTask}"
|
||||
}
|
||||
]
|
||||
}
|
||||
10
.vscode/settings.json
vendored
10
.vscode/settings.json
vendored
@@ -1,10 +0,0 @@
|
||||
{
|
||||
"gitdoc.enabled": false,
|
||||
"typescript.tsdk": "node_modules/typescript/lib",
|
||||
"files.exclude": {
|
||||
"**/*-mdjs-generated.js": true,
|
||||
},
|
||||
"search.exclude": {
|
||||
"**/*-mdjs-generated.js": true,
|
||||
}
|
||||
}
|
||||
29
.vscode/tasks.json
vendored
29
.vscode/tasks.json
vendored
@@ -1,29 +0,0 @@
|
||||
// See https://go.microsoft.com/fwlink/?LinkId=733558
|
||||
// for the documentation about the tasks.json format
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"type": "npm",
|
||||
"script": "watch",
|
||||
"problemMatcher": "$tsc-watch",
|
||||
"isBackground": true,
|
||||
"presentation": {
|
||||
"reveal": "never"
|
||||
},
|
||||
"group": {
|
||||
"kind": "build",
|
||||
"isDefault": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"label": "Compile vscode-rocket",
|
||||
"type": "npm",
|
||||
"script": "compile",
|
||||
"path": "packages/vscode-rocket/",
|
||||
"group": "build",
|
||||
"problemMatcher": [],
|
||||
"detail": "tsc -p ./"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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) repository by hitting the `fork` button on the GitHub page.
|
||||
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.
|
||||
|
||||
Next, clone our repository onto your computer.
|
||||
Next, clone our repository onto your computer with this command (replacing YOUR_USERNAME with your actual GitHub username)
|
||||
|
||||
```sh
|
||||
git clone git@github.com:modernweb-dev/rocket.git
|
||||
```
|
||||
|
||||
Once cloning is complete, change directory to the repository.
|
||||
Once cloning is complete, change directory to the repo.
|
||||
|
||||
```sh
|
||||
cd rocket
|
||||
```
|
||||
|
||||
Now add your fork as a remote (replacing YOUR_USERNAME with your GitHub username).
|
||||
Now add your fork as a remote
|
||||
|
||||
```sh
|
||||
git remote add fork git@github.com:<YOUR_USERNAME>/rocket.git
|
||||
git remote add fork git@github.com:<YOUR_NAME>/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, then 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 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 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)
|
||||
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)
|
||||
|
||||
### 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.
|
||||
|
||||
## Creating a Changeset
|
||||
## Create 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).
|
||||
|
||||
27
README.md
27
README.md
@@ -1,4 +1,4 @@
|
||||
> This project is in its BETA phase
|
||||
> This project is in it's BETA phase
|
||||
|
||||
<p align="center">
|
||||
<img
|
||||
@@ -19,11 +19,6 @@
|
||||
src="https://img.shields.io/badge/twitter-@modern_web_dev-1DA1F3?style=flat-square"
|
||||
alt="Follow @modern_web_dev on Twitter"
|
||||
/></a>
|
||||
<a href="https://open.vscode.dev/modernweb-dev/rocket"
|
||||
><img
|
||||
src="https://open.vscode.dev/badges/open-in-vscode.svg"
|
||||
alt="Open in VS Code"
|
||||
/></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
@@ -38,7 +33,7 @@
|
||||
|
||||
**The modern web setup for static sites with a sprinkle of JavaScript!**
|
||||
|
||||
- **Meta Framework:** Build on top of giants like <a href="https://lit.dev/">Lit</a>, <a href="https://rollupjs.org/">Rollup</a> and <a href="https://www.modern-web.dev/">Modern Web</a>.
|
||||
- **Meta Framework:** Build on top of giants like <a href="https://www.11ty.dev/">eleventy</a>, <a href="https://rollupjs.org/">Rollup</a>, and <a href="https://www.modern-web.dev/">Modern Web</a>.
|
||||
- **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..
|
||||
|
||||
@@ -46,30 +41,20 @@
|
||||
<a href="https://rocket.modern-web.dev/guides/"><strong>Explore the Rocket Guides ▶</strong></a>
|
||||
</p>
|
||||
|
||||
## The Goal for Rocket
|
||||
## The goal for Rocket
|
||||
|
||||
> Our goal is to provide developers with a meta framework for static websites with a sprinkle of JavaScript.
|
||||
> 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 detail of every underlying tool that gets used.
|
||||
You can still tweak every details of every underlying tool that get's used.
|
||||
|
||||
Rocket is part of the [Modern Web Family](https://twitter.com/modern_web_dev).
|
||||
|
||||
## Quick Start
|
||||
|
||||
```
|
||||
mkdir test-rocket
|
||||
cd test-rocket
|
||||
npm init -y
|
||||
npm i @rocket/cli@alpha @rocket/launch@alpha @11ty/eleventy-cache-assets typescript
|
||||
npx rocket init
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
We are always looking for contributors of all skill levels! If you're looking to ease your way into the project, try out a [good first issue](https://github.com/modernweb-dev/rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
|
||||
|
||||
If you are interested in helping contribute to Modern Web, please take a look at our [Contributing Guide](https://github.com/modernweb-dev/rocket/blob/main/CONTRIBUTING.md). Also, feel free to drop into [slack](https://rocket.modern-web.dev/about/slack/) and say hi. 👋
|
||||
If you are interested in helping contribute to Modern Web, please take a look at our [Contributing Guide](https://github.com/modernweb-dev/rocket/blob/main/CONTRIBUTING.md). Also, feel free to drop into [slack](https://rocket.modern-web.dev/discover/slack/) and say hi. 👋
|
||||
|
||||
### Financial Contributors
|
||||
|
||||
|
||||
41
TODO.md
41
TODO.md
@@ -1,41 +0,0 @@
|
||||
## Features
|
||||
|
||||
- Rename "options.docsDir" to "options.inputDir"
|
||||
- recursive rendering of lit / html / and markdown
|
||||
- convert `<meta name="menu:link.text" content="Docs" />` to `export const menuLinkText = 'Docs';`
|
||||
- "import" markdown with frontmatter
|
||||
- export const mdCleanup = false; => to not clean up auto generated md files for this page
|
||||
- add helper for layouts
|
||||
- Add "menuExclude" => to actually exclude the menu item
|
||||
|
||||
## Bugs
|
||||
|
||||
- write to `_site-dev` instead of `_site` while using `rocket start`
|
||||
- nested `recursive.data.js` do not overwrite the parent data
|
||||
- rocketGeneratedMdInJs => converted-md-source
|
||||
- rocketGeneratedFromMd => converted-md
|
||||
- support <!-- asdf --> in markdown
|
||||
- ssr render can just be a string concat
|
||||
|
||||
## Error Handling
|
||||
|
||||
- make error nice for "needs function export default () => html` instead of just export default html`"
|
||||
- make error nice for parent page not found in index => auto generate page? 🤔
|
||||
|
||||
## Examples
|
||||
|
||||
- docs site, blog (simple), blog (complex), minimal
|
||||
- add stackblitz/codesandbox examples
|
||||
|
||||
- Example: export variable and use it in rendering
|
||||
- Example: fetch data from an api and display it
|
||||
- Example: usage of image
|
||||
|
||||
## later
|
||||
|
||||
- support `@change` in markdown
|
||||
- support "hey ${foo.map(f => `${f} + 1`)}"
|
||||
|
||||
## consider
|
||||
|
||||
- Replace magic "resolve:pkg/foo.css" with a directive `${resolve()}`?
|
||||
@@ -1,177 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/10--first-pages/10--getting-started.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Getting Started
|
||||
|
||||
Rocket has the following prerequisites:
|
||||
|
||||
- [Node 14+](https://nodejs.org/en/)
|
||||
|
||||
Make sure they are installed before proceeding.
|
||||
|
||||
## Setup
|
||||
|
||||
The fastest way to get started is by using an existing preset like the launch preset.
|
||||
|
||||
### Step 1. Initialize the Project Package
|
||||
|
||||
Start by creating an empty folder for your project
|
||||
|
||||
```bash copy
|
||||
mkdir my-project
|
||||
cd my-project
|
||||
```
|
||||
|
||||
Then initialize a package.json file
|
||||
|
||||
<code-tabs collection="package-managers" default-tab="npm" align="end">
|
||||
|
||||
```bash tab npm
|
||||
npm init -y
|
||||
```
|
||||
|
||||
```bash tab yarn
|
||||
yarn init -y
|
||||
```
|
||||
|
||||
```bash tab pnpm
|
||||
pnpm init -y
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
### Step 2. Install dependencies
|
||||
|
||||
<code-tabs collection="package-managers" default-tab="npm" align="end">
|
||||
|
||||
```bash tab npm
|
||||
npm install --save-dev @rocket/cli @rocket/launch
|
||||
```
|
||||
|
||||
```bash tab yarn
|
||||
yarn add -D @rocket/cli @rocket/launch
|
||||
```
|
||||
|
||||
```bash tab pnpm
|
||||
pnpm add -D @rocket/cli @rocket/launch
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
### Step 3. Bootstrap the project
|
||||
|
||||
<code-tabs collection="package-managers" default-tab="npm" align="end">
|
||||
|
||||
```bash tab npm
|
||||
npx rocket bootstrap
|
||||
```
|
||||
|
||||
```bash tab yarn
|
||||
yarn rocket bootstrap
|
||||
```
|
||||
|
||||
```bash tab pnpm
|
||||
pnpx rocket bootstrap
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
The `bootstrap` command creates four files in your repo:
|
||||
|
||||
- `rocket.config.js` containing a minimal rocket config
|
||||
- `docs/index.md` your first page
|
||||
- `.gitignore` containing rocket's build artifacts
|
||||
- `.vscode/settings.json` hide build artifacts in your vscode
|
||||
|
||||
It also set the package `type` to `"module"` and adds a `start` and `docs` package scripts.
|
||||
|
||||
<inline-notification type="warning">
|
||||
|
||||
If you don't want to use the `module` package type, make sure to rename the generated config file to `rocket.config.mjs`.
|
||||
|
||||
</inline-notification>
|
||||
|
||||
<details><summary>Default Files Contents</summary>
|
||||
|
||||
<code-tabs default-tab="rocket.config.js">
|
||||
|
||||
```js tab rocket.config.js
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
presets: [rocketLaunch()],
|
||||
};
|
||||
```
|
||||
|
||||
```md tab docs/index.md
|
||||
# Welcome to Your Rocket Site
|
||||
|
||||
Add your markdown content here.
|
||||
```
|
||||
|
||||
```html tab .gitignore
|
||||
## Rocket ignore files (need to be the full relative path to the folders) docs/_merged_data/
|
||||
docs/_merged_assets/ docs/_merged_includes/
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
</details>
|
||||
|
||||
## Add your First Page
|
||||
|
||||
Bootstrap created the file `docs/index.md`. Open it in your editor and change it to suit your needs.
|
||||
|
||||
<small>NOTE: This tutorial assumes you are familiar with Markdown, for page authoring.</small>
|
||||
|
||||
```md
|
||||
# Welcome to Your Rocket Site
|
||||
|
||||
Add your markdown content here.
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Startup
|
||||
|
||||
Now you can launch your site locally with
|
||||
|
||||
<code-tabs collection="package-managers" default-tab="npm" align="end">
|
||||
|
||||
```bash tab npm
|
||||
npm start
|
||||
```
|
||||
|
||||
```bash tab yarn
|
||||
yarn start
|
||||
```
|
||||
|
||||
```bash tab pnpm
|
||||
pnpx start
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
## Taking Inventory Before Adding Pages:
|
||||
|
||||
We're about to add both content and navigation at the same time.
|
||||
|
||||
It can be helpful to take an inventory, before we start, to separate basic setup from the creation of content and navigation.
|
||||
|
||||
- We built the project with basic npm commands
|
||||
- Added a couple required files manually
|
||||
- Adjusted package.json
|
||||
- **docs/index.md** to seed the content
|
||||
- Launches with `npm start`
|
||||
|
||||
That's all it takes to get a new super-fast and powerful site, complete with a service worker, default styling, navigation, and ready to deploy as a plain old static files.
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
@@ -1,49 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/10--first-pages/30--use-javascript.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Use JavaScript
|
||||
|
||||
If you would like to add JavaScript to a page, you can do it inline using the `script` markdown directive. The script you write runs on the page as a module.
|
||||
|
||||
````markdown
|
||||
```js script
|
||||
const message = 'Hello, World!';
|
||||
console.log(message);
|
||||
```
|
||||
````
|
||||
|
||||
Adding the above will log `Hello, World!` to the console without adding a global `message` variable.
|
||||
|
||||
This can be useful for importing web components and using them in Markdown. Imagine you had some `magic-reveal` element that you wanted to use on a page:
|
||||
|
||||
````markdown
|
||||
```js script
|
||||
import 'magic-reveal/magic-reveal.js';
|
||||
```
|
||||
|
||||
<magic-reveal>
|
||||
|
||||
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.
|
||||
|
||||
</magic-reveal>
|
||||
````
|
||||
|
||||
## Component Story Format
|
||||
|
||||
You can also add storybook-style CSF (v2 only) stories to a page using `js story` or `js preview-story`, just make sure to import `html` from `@mdjs/mdjs-preview` instead of from `lit` or `lit-html`.
|
||||
|
||||
````markdown
|
||||
```js story
|
||||
import { html } from '@mdjs/mdjs-preview';
|
||||
|
||||
export const StoryPreview = () => html` <p>Use stories in Rocket!</p> `;
|
||||
```
|
||||
````
|
||||
@@ -1,9 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/10--first-pages/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () => html`<h1>First Pages</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,44 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/20--presets/10--getting-started.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Getting Started
|
||||
|
||||
Presets are partial rocket configs that combine any number of plugins to add specific features. Rocket is built on these presets, like `rocketLaunch`, `rocketBlog`, and `rocketSearch`
|
||||
|
||||
You can use a preset via the config by adding it to the `presets` array
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js copy
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
import { rocketBlog } from '@rocket/blog';
|
||||
import { rocketSearch } from '@rocket/search';
|
||||
|
||||
/** @type {import('@rocket/cli').RocketCliOptions} */
|
||||
export default ({
|
||||
presets: [rocketLaunch(), rocketBlog(), rocketSearch()],
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Community Presets
|
||||
|
||||
There are a number of community-made presets available:
|
||||
|
||||
<!--
|
||||
-- Thank you for your interest in rocket. To add your preset,
|
||||
-- follow the format below. Please add your preset in alphabetical order.
|
||||
-->
|
||||
|
||||
- [rocket-preset-code-tabs](https://www.npmjs.com/package/rocket-preset-code-tabs) - Add tab elements for code blocks
|
||||
- [rocket-preset-custom-elements-manifest](https://www.npmjs.com/package/rocket-preset-custom-elements-manifest) - Documents code generation for JavaScript libraries, particularly custom elements.
|
||||
- [rocket-preset-markdown-directive](https://www.npmjs.com/package/rocket-preset-markdown-directive) - Add your own custom md code block directives
|
||||
- [rocket-preset-playground-elements](https://www.npmjs.com/package/rocket-preset-playground-elements) - Live code editors that run in-browser
|
||||
- [rocket-preset-slide-decks](https://www.npmjs.com/package/rocket-preset-slide-decks) - Slide decks in Markdown and HTML
|
||||
- [rocket-preset-webcomponents-dev](https://www.npmjs.com/package/rocket-preset-webcomponents-dev) - Live code editors that run on webcomponents.dev
|
||||
|
||||
> Want your plugin listed here? Please [create a PR](https://github.com/modernweb-dev/rocket/edit/main/docs/guides/presets/getting-started.md)!
|
||||
@@ -1,34 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/20--presets/20--overriding.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Overriding
|
||||
|
||||
All loaded presets will be combined but you can override each file.
|
||||
|
||||
Take a look at `docs/_merged_includes` and override what you want to override by placing the same filename into `_includes`.
|
||||
|
||||
For example, to override the css files loaded in the `<head>`,
|
||||
|
||||
```bash
|
||||
cp docs/_merged_includes/_joiningBlocks/head/40-stylesheets.njk \
|
||||
docs/_includes/_joiningBlocks/head/40-stylesheets.njk
|
||||
```
|
||||
|
||||
then edit the file to suit your needs.
|
||||
|
||||
Also works for `_assets`, `_data` ...
|
||||
|
||||
<inline-notification type="warning">
|
||||
|
||||
If you don't [add `.eleventyignore`](/guides/first-pages/getting-started/#setup), you may receive error messages when running `rocket build`.
|
||||
|
||||
</inline-notification>
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
@@ -1,11 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/20--presets/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () => html`
|
||||
<h1>Presets</h1>
|
||||
<meta name="menu:exclude" content="true" />
|
||||
`;
|
||||
@@ -1,9 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/30--configuration/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () => html`<h1>Configuration</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,62 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/40--go-live/10--overview.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Overview
|
||||
|
||||
A few things are usually needed before going live "for real".
|
||||
|
||||
## Add a Not Found Page
|
||||
|
||||
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 Launch preset](../../docs/presets/launch.md) ships a default 404 template you can use.
|
||||
|
||||
To enable it, you need to create a `404.md` and use the 404 layout.
|
||||
|
||||
👉 `docs/404.md`
|
||||
|
||||
```markdown copy
|
||||
---
|
||||
layout: layout-404
|
||||
permalink: 404.html
|
||||
---
|
||||
```
|
||||
|
||||
This results in a `404.html` page, which will do nothing by itself. But many hosting services like netlify or firebase, for example will redirect 404s to this `404.html` by default.
|
||||
|
||||
If the hosting provider doesn't already do this, then you may be able to accomplish it via some settings for example by using a `.htaccess` file in case of an apache server.
|
||||
|
||||
## 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:
|
||||
|
||||
👉 `docs/sitemap.njk`
|
||||
|
||||
```markdown copy
|
||||
---
|
||||
layout: layout-raw
|
||||
permalink: /sitemap.xml
|
||||
eleventyExcludeFromCollections: true
|
||||
---
|
||||
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
{% raw %}{% for page in collections.all %}
|
||||
{%- if page.url !== '/404.html' -%}
|
||||
<url>
|
||||
<loc>{{ rocketConfig.absoluteBaseUrl }}{{ page.url | url }}</loc>
|
||||
<lastmod>{{ page.date.toISOString() }}</lastmod>
|
||||
<changefreq>{{ page.data.changeFreq if page.data.changeFreq else "monthly" }}</changefreq>
|
||||
</url>
|
||||
{%- endif -%}
|
||||
{% endfor %}{% endraw %}
|
||||
</urlset>
|
||||
```
|
||||
@@ -1,170 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/40--go-live/20--social-media.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Social Media
|
||||
|
||||
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:
|
||||
|
||||
There are multiple ways you can modify it.
|
||||
|
||||
Note: If your logo has an `<?xml>` tag it will throw an error as it will be inlined into this SVG and nested XML tags are not allowed.
|
||||
|
||||
## Setting it via Front Matter
|
||||
|
||||
You can create your own image and link it with something like this
|
||||
|
||||
```markdown copy
|
||||
---
|
||||
socialMediaImage: path/to/my/image.png
|
||||
---
|
||||
```
|
||||
|
||||
## Providing Your Own Text
|
||||
|
||||
Sometimes extracting the title + title of parent is not enough but you still want to use the "default image".
|
||||
|
||||
You can create an `11tydata.cjs` file next to your page. If your page is `docs/guides/overview.md` then you create a `docs/guides/overview.11tydata.cjs`.
|
||||
|
||||
In there you can use the default `createSocialImage` but provide your own values.
|
||||
|
||||
```js copy
|
||||
const { createSocialImage } = require('@rocket/cli');
|
||||
|
||||
module.exports = async function () {
|
||||
const socialMediaImage = await createSocialImage({
|
||||
title: 'Learning Rocket',
|
||||
subTitle: 'Have a website',
|
||||
subTitle2: 'in 5 Minutes',
|
||||
footer: 'Rocket Guides',
|
||||
// you can also override the svg only for this page by providing
|
||||
// createSocialImageSvg: async () => '{%raw%}<svg>...</svg>{%endraw%}'
|
||||
});
|
||||
return {
|
||||
socialMediaImage,
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js copy
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
/** @type {import('@rocket/cli').RocketCliOptions} */
|
||||
export default ({
|
||||
setupEleventyComputedConfig: [
|
||||
adjustPluginOptions('socialMediaImage', {
|
||||
createSocialImageSvg: async ({
|
||||
title = '',
|
||||
subTitle = '',
|
||||
subTitle2 = '',
|
||||
footer = '',
|
||||
logo = '',
|
||||
}) => {
|
||||
let svgStr = `
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630" style="fill: #ecedef;">
|
||||
<defs/>
|
||||
<rect width="100%" height="100%" fill="#38393e"/>
|
||||
<g transform="matrix(0.45, 0, 0, 0.45, 300, 60)">${logo}</g>
|
||||
<g style="
|
||||
font-size: 70px;
|
||||
text-anchor: middle;
|
||||
font-family: 'Bitstream Vera Sans','Helvetica',sans-serif;
|
||||
font-weight: 700;
|
||||
">
|
||||
<text x="50%" y="470">
|
||||
${title}
|
||||
</text>
|
||||
<text x="50%" y="520" style="font-size: 30px;">
|
||||
${subTitle}
|
||||
</text>
|
||||
</g>
|
||||
<text x="10" y="620" style="font-size: 30px; fill: gray;">
|
||||
${footer}
|
||||
</text>
|
||||
</svg>
|
||||
`;
|
||||
return svgStr;
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## 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 use a template system.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
<code-tabs default-tab="rocket.config.js">
|
||||
|
||||
```js tab rocket.config.js
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
/** @type {import('@rocket/cli').RocketCliOptions} */
|
||||
export default ({
|
||||
setupEleventyComputedConfig: [
|
||||
adjustPluginOptions('socialMediaImage', {
|
||||
createSocialImageSvg: async (args = {}) => {
|
||||
const svgBuffer = await fs.promises.readFile('/path/to/your/template.svg');
|
||||
const svg = logoBuffer.toString();
|
||||
return nunjucks.renderString(svg, args);
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
```svg tab /path/to/your/template.svg
|
||||
{%raw%}<svg xmlns="http://www.w3.org/2000/svg" fill="#e63946" viewBox="0 0 511.998 511.998">
|
||||
<text font-family="'Open Sans', sans-serif" font-size="39" transform="translate(422.99 408.53)">
|
||||
<tspan x="-89.26" y="12.25">{{ title }}</tspan>
|
||||
</text>
|
||||
<path d="M98.649 430.256c-46.365 28.67-71.17 30.939-78.916 23.51-7.75-7.433-6.519-32.307 20.182-79.832 24.953-44.412 65.374-96.693 113.818-147.211l-11.279-10.817c-49.33 51.442-90.583 104.845-116.163 150.373-19.228 34.22-37.848 79.134-17.375 98.766 5.84 5.6 13.599 7.935 22.484 7.935 22.269 0 51.606-14.677 75.469-29.432 44.416-27.464 96.044-70.919 145.373-122.362l-11.279-10.817c-48.446 50.519-98.987 93.095-142.314 119.887zM254.734 294.95l-18.47-17.71 10.816-11.281 18.47 17.71zM285.516 324.473l-18.47-17.71 10.816-11.28 18.47 17.71zM315.543 317.807l-73.886-70.847 10.816-11.28 73.886 70.846zM500.916 41.287c-7.769 1.59-76.412 16.062-93.897 34.294l-50.728 52.899-114.703-3.629-39.198 40.876 79.28 40.569-21.755 22.687 72.848 69.858 21.755-22.687 43.857 77.51 39.197-40.876-8.433-114.451 50.727-52.899c17.485-18.234 29.067-87.422 30.331-95.251l1.801-11.169-11.082 2.269zM228.209 161.383l19.842-20.692 93.688 2.964-48.775 50.864-64.755-33.136zm173.423 166.303l-35.822-63.308 48.776-50.865 6.886 93.482-19.84 20.691zm-69.334-50.943l-50.287-48.223L412.89 92.037l50.288 48.223-130.88 136.483zm140.711-148.707l-48.316-46.334c14.54-8.427 44.787-17.217 68.076-22.632-4.433 23.497-11.949 54.085-19.76 68.966z"/>
|
||||
<path d="M326.335 257.25l-24.628-23.614 10.816-11.28 24.628 23.615zM431.385 134.414l-11.808 12.315-11.28-10.816 11.808-12.315zM401.838 165.183l-11.28-10.816 11.807-12.314 11.28 10.816zM384.121 183.66l-11.28-10.816 11.807-12.314 11.28 10.816zM175.19 184.515l11.051 11.05-23.582 23.582-11.05-11.05zM190.903 168.796l11.05 11.052-7.863 7.86-11.05-11.052z"/>
|
||||
</svg>{%endraw%}
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Enabling / Disabling
|
||||
|
||||
Generating images from SVG is quite fast but it can still add that's why by default during `rocket start` there will be no social media images created.
|
||||
|
||||
If you with so create them also during start you can
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js copy
|
||||
export default ({
|
||||
start: {
|
||||
createSocialMediaImages: true,
|
||||
},
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Similarly, if you never want to create social media images even during build then you can globally disable it via
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js copy
|
||||
export default ({
|
||||
createSocialMediaImages: true,
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -1,9 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/40--go-live/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () => html`<h1>Go Live</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,28 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/index.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Learning Rocket
|
||||
|
||||
<meta name="menu:link.text" content="Guides">
|
||||
|
||||
Rocket helps you generate static pages from Markdown files while giving you the flexibility to sprinkle in some JavaScript where needed.
|
||||
|
||||
- [First Pages](./first-pages/getting-started/) Learn how to bootstrap and run a Rocket site
|
||||
- [Adding Pages](./first-pages/adding-pages/) Create your own content pages
|
||||
- [Linking](./first-pages/link-to-other-pages/) Link between yuor markdown pages
|
||||
- [Managing Sidebar](./first-pages/manage-sidebar/) Customize your site's navigation
|
||||
- [Use JavaScript](./first-pages/use-javascript/) Write inline scripts in markdown
|
||||
- [URLs](./first-pages/urls/) Customize your pages' permalinks
|
||||
- [Layouts](./first-pages/layouts/) Give your page a custom layout
|
||||
- [Presets](./presets/getting-started/) Customize Rocket with config presets
|
||||
- [Overriding](./presets/overriding/) Override preset templates
|
||||
- [Using Templates](./presets/using-templates/) Make use of preset templates
|
||||
- [Create Your Own](./presets/create-your-own/getting-started/) Write and publish your own presets
|
||||
- [Configuration](./configuration/getting-started/) Make Rocket your own
|
||||
- [Go Live](./go-live/overview/) Publish your site
|
||||
- [Social Media](./go-live/social-media/) Generate social images
|
||||
@@ -1,105 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/10--configuration/10--overview.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Overview
|
||||
|
||||
The configuration file is `rocket.config.js` or `rocket.config.mjs`.
|
||||
|
||||
The config files consist of the following parts:
|
||||
|
||||
```js
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
presets: [rocketLaunch()],
|
||||
emptyOutputDir: true,
|
||||
pathPrefix: 'subfolder-only-for-build',
|
||||
};
|
||||
```
|
||||
|
||||
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
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
// 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)
|
||||
setupDevServerAndBuildPlugins: [],
|
||||
|
||||
// add a plugin to the web dev server (will not be wrapped) (e.g. esbuild for TypeScript)
|
||||
setupDevServerPlugins: [],
|
||||
|
||||
// add a plugin to the rollup build (e.g. optimization steps)
|
||||
setupBuildPlugins: [],
|
||||
|
||||
// add a plugin to the cli (e.g. a new command like "rocket my-command")
|
||||
setupCliPlugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
## Adding Rollup Plugins
|
||||
|
||||
For some projects you might want to enable non-standard behaviors like importing JSON files as JavaScript.
|
||||
|
||||
```js
|
||||
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.
|
||||
|
||||
For these cases you can use `setupDevServerAndBuildPlugins`, which will automatically add the plugin for you to both Rollup and dev-server:
|
||||
|
||||
```js
|
||||
import json from '@rollup/plugin-json';
|
||||
import { addPlugin } from 'plugins-manager';
|
||||
|
||||
/** @type {import('@rocket/cli').RocketCliOptions} */
|
||||
export default {
|
||||
setupDevServerAndBuildPlugins: [
|
||||
addPlugin({ name: 'json', plugin: json, location: 'top', options: { my: 'settings' } }),
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
All plugins which are either default or are added via a preset can still be adjusted by using `adjustPluginOptions`.
|
||||
|
||||
```js
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
/** @type {import('@rocket/cli').RocketCliOptions} */
|
||||
export default {
|
||||
setupDevServerAndBuildPlugins: [adjustPluginOptions('json', { my: 'overwrite settings' })],
|
||||
};
|
||||
```
|
||||
|
||||
## Advanced
|
||||
|
||||
Sometimes you need even more control over specific settings.
|
||||
|
||||
### Rollup
|
||||
|
||||
For example if you wanna add an `acron` plugin to rollup
|
||||
|
||||
```js
|
||||
import { importAssertions } from 'acorn-import-assertions';
|
||||
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
rollup: config => ({
|
||||
...config,
|
||||
acornInjectPlugins: [importAssertions],
|
||||
}),
|
||||
};
|
||||
```
|
||||
@@ -1,54 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/10--configuration/20--service-worker.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Service Worker
|
||||
|
||||
Rocket does come with a default service worker that will
|
||||
|
||||
- cache already visited pages
|
||||
- cache assets of visited pages (up to 100 files then it replaces older entries)
|
||||
- reload the page if a newer html page version is available on service worker activation
|
||||
|
||||
## Adjusting the file name
|
||||
|
||||
Changing the service worker file name can be quite a hassle so you can adjust generate file name via a config.
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
```js
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
serviceWorkerName: 'my-service-worker-name.js',
|
||||
};
|
||||
```
|
||||
|
||||
## Meet the Service Worker
|
||||
|
||||
The default service worker will work for many scenarios however your needs my vary.
|
||||
To enable different service worker strategies you can replace the default service worker code by providing a file at `_assets/service-worker.js`.
|
||||
This file will be auto transformed and generated in the root of the website using the defined `serviceWorkerName`.
|
||||
|
||||
For inspiration, you can take a look at the default config.
|
||||
|
||||
[https://github.com/modernweb-dev/rocket/blob/main/packages/cli/preset/\_assets/service-worker.js](https://github.com/modernweb-dev/rocket/blob/main/packages/cli/preset/_assets/service-worker.js)
|
||||
|
||||
Be sure to check out [workbox](https://developers.google.com/web/tools/workbox) for more service worker magic.
|
||||
|
||||
And if you wanna have a 30 minutes crash course we highly recommend the talk [Service Workers For The Rest Of Us](https://vimeo.com/362260166) by [Philip Walton](https://twitter.com/philwalton).
|
||||
|
||||
## Registration
|
||||
|
||||
The registration happens via another file that you can also overwrite at `_assets/scripts/registerServiceWorker.js`.
|
||||
|
||||
Below you find the default implementation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
{{ '/_assets/scripts/registerServiceWorker.js' | asset | toAbsPath | inlineFilePath; }}
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -1,322 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/10--configuration/30--images.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Images
|
||||
|
||||
Rocket does handle content images automatically by
|
||||
|
||||
- producing multiple sizes so users download images that are meant for their resolution
|
||||
- outputting multiple formats so the device can choose the best image format it supports
|
||||
|
||||
And the best thing about is you don't need to do anything.
|
||||
|
||||
## Usage
|
||||
|
||||
If you are using markdown images you are good to go.
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
will result in
|
||||
|
||||
```html
|
||||
<picture>
|
||||
<source
|
||||
type="image/avif"
|
||||
srcset="/images/5f03d82-300.avif 300w, /images/5f03d82-820.avif 820w"
|
||||
sizes="(min-width: 1024px) 820px, calc(100vw - 20px)"
|
||||
/>
|
||||
<source
|
||||
type="image/jpeg"
|
||||
srcset="/images/5f03d82-300.jpeg 300w, /images/5f03d82-820.jpeg 820w"
|
||||
sizes="(min-width: 1024px) 820px, calc(100vw - 20px)"
|
||||
/>
|
||||
<img
|
||||
alt="My Image"
|
||||
rocket-image="responsive"
|
||||
src="/images/5f03d82-300.jpeg"
|
||||
width="300"
|
||||
height="158"
|
||||
loading="lazy"
|
||||
decoding="async"
|
||||
/>
|
||||
</picture>
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
The main benefit is that we can serve the correct size and optimal image format depending on the browser capabilities leading to optimal loading times on different systems.
|
||||
|
||||
- Smaller images for smaller screens
|
||||
|
||||
When providing `srcset` and `sizes` the browser can decide which image makes the most sense to download.
|
||||
This will lead to much faster websites especially on mobile where smaller images can be served.
|
||||
If you wanna know more check out [The anatomy of responsive images](https://jakearchibald.com/2015/anatomy-of-responsive-images/).
|
||||
|
||||
- Serve the best/smallest image format the browser understands
|
||||
|
||||
There are currently ~3 formats you may want to consider `avif`, `webp` and `jpg`. The improvements are huge [webp is ~30% and avif ~50%](https://www.ctrl.blog/entry/webp-avif-comparison.html) smaller then the original jpg.
|
||||
|
||||
## Adding a caption
|
||||
|
||||
If you want to describe your image in more detail you can add a caption
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
will result in
|
||||
|
||||
```html
|
||||
<figure>
|
||||
<picture>
|
||||
<!-- picture code the same as above -->
|
||||
</picture>
|
||||
<figcaption>My caption text</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
## Adjusting options
|
||||
|
||||
Under the hood it is using [11ty/image](https://www.11ty.dev/docs/plugins/image/) and all it's options are available.
|
||||
|
||||
<inline-notification type="tip">
|
||||
|
||||
If you are using a layout preset like `@rocket/launch` then you probably don't want to touch/change these options as the preset will set it for you accordion to its layout needs.
|
||||
|
||||
The default preset for regular markdown content is available as `responsive`.
|
||||
|
||||
</inline-notification>
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default ({
|
||||
imagePresets: {
|
||||
responsive: {
|
||||
widths: [300, 820],
|
||||
formats: ['avif', 'jpeg'],
|
||||
sizes: '(min-width: 1024px) 820px, calc(100vw - 20px)',
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Ignoring Images
|
||||
|
||||
Files ending in `.svg` or that include `rocket-ignore.` will remain untouched.
|
||||
|
||||
For example
|
||||
|
||||
```md
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
becomes
|
||||
|
||||
```html
|
||||
<img src="logo.svg" alt="Logo stays svg" rocket-image="responsive" />
|
||||
<img src="my-image.rocket-unresponsive.jpg" alt="Ignore by file name" rocket-image="responsive" />
|
||||
<picture>[...] </picture>
|
||||
```
|
||||
|
||||
### Adjusting ignore function
|
||||
|
||||
The default ignore function looks like this
|
||||
|
||||
```js
|
||||
/**
|
||||
* The default responsive ignore function will ignore files
|
||||
* - ending in `.svg`
|
||||
* - containing `rocket-unresponsive.`
|
||||
*
|
||||
* @param {object} opts
|
||||
* @param {string} opts.src
|
||||
* @param {string} opts.title
|
||||
* @param {string} opts.alt
|
||||
* @param {{name: string, value: string}[]} opts.attributes
|
||||
* @returns {boolean}
|
||||
*/
|
||||
function ignore({ src }) {
|
||||
return src.endsWith('svg') || src.includes('rocket-unresponsive.');
|
||||
}
|
||||
```
|
||||
|
||||
and you can adjust it by setting it via the `imagePreset`.
|
||||
|
||||
For this example we want to also ignore `.jpeg` files.
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default ({
|
||||
imagePresets: {
|
||||
responsive: {
|
||||
// ...
|
||||
ignore: ({ src }) =>
|
||||
src.endsWith('.jpeg') || src.endsWith('svg') || src.includes('rocket-unresponsive.'),
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
With that setting we get the following behavior
|
||||
|
||||
```md
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
becomes
|
||||
|
||||
```html
|
||||
<img src="logo.svg" alt="Logo stays svg" rocket-image="responsive" />
|
||||
<img src="my-image.rocket-unresponsive.jpg" alt="Ignore by file name" rocket-image="responsive" />
|
||||
<img src="my-image.jpeg" alt="My Image Alternative Text" rocket-image="responsive" />
|
||||
```
|
||||
|
||||
## Defining your own presets
|
||||
|
||||
You can add your own image preset like so
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default ({
|
||||
imagePresets: {
|
||||
'my-image-preset': {
|
||||
widths: [30, 60],
|
||||
formats: ['avif', 'jpeg'],
|
||||
sizes: '(min-width: 1024px) 30px, 60px',
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Once that `imagePreset` is defined you can use it by adding it to any `img` tag.
|
||||
|
||||
```html
|
||||
<img src="./path/to/image.jpg" alt="my alt" rocket-image="my-image-preset" />
|
||||
```
|
||||
|
||||
## How does it work?
|
||||
|
||||
1. Each markdown image `` gets rendered as `<img src="path/to/image.jpg" alt="my image" rocket-image="responsive">`
|
||||
2. We parse the html output and process every image which has `rocket-image`
|
||||
3. Get the image preset settings from the name e.g. `rocket-image="my-image-preset"` reads `imagePreset['my-image-preset']`
|
||||
4. Pass the settings onto `@11ty/image` to generate the image sizes and formats
|
||||
5. With the metadata we render the html
|
||||
|
||||
## Default Formats
|
||||
|
||||
An [image file format](https://en.wikipedia.org/wiki/Image_file_formats) is a way of storing common image formats. Each format varies in capabilities like compression algorithm, availability, progressive rendering, encode and decode time, ...
|
||||
Ultimately newer formats are usually smaller while retaining image quality which leads to faster websites.
|
||||
|
||||
By default, we generate `avif` and `jpg` because
|
||||
|
||||
- we only want to generate two versions to limit CI time and html size
|
||||
- `avif` is significantly smaller than `webp`
|
||||
- `avif` is available in
|
||||
- Chrome since August 2020
|
||||
- Firefox since June 2021
|
||||
- `jpg` as a fallback for Edge, Safari, IE11
|
||||
- `webp` would only help a small percentage of Edge & Safari on macOS 11 (Big Sur) users
|
||||
|
||||
This leads to the following situation:
|
||||
|
||||
- Chrome, Firefox gets the small `avif`
|
||||
- Edge, Safari, IE11 gets the bigger `jpg`
|
||||
|
||||
To learn more about `avif` take a look at [AVIF has landed](https://jakearchibald.com/2020/avif-has-landed/).
|
||||
|
||||
If you want to add `webp` (or replace `avif` with it) you can do so by setting the formats
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default ({
|
||||
imagePresets: {
|
||||
responsive: {
|
||||
formats: ['avif', 'webp', 'jpeg'],
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## Default widths
|
||||
|
||||
In order to understand the need for having a single image in multiple resolutions we need to understand the our website is served to many different environments and each may come with its own specific device pixel ratio (DPR). The device pixel ratio is the ratio between physical pixels and logical pixels. For instance, the Galaxy S20 report a device pixel ratio of 3, because the physical linear resolution is triple the logical linear resolution.
|
||||
|
||||
Physical resolution: 1440 x 3200
|
||||
Logical resolution: 480 x 1067
|
||||
|
||||
And 1440 / 480 = 3.
|
||||
|
||||
By default, we generate the following widths `600`, `900` and `1640` because
|
||||
|
||||
- we only want to generate a small amount of widths to limit CI time and service worker cache size
|
||||
- `600` is good for mobile with DRP 2
|
||||
- `900` is good for mobile with DRP 3 and desktop with DPR of 1
|
||||
- `1640` is good for desktop with DPR of 2
|
||||
|
||||
If you want to add more widths you can add them to `widths`.
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default ({
|
||||
imagePresets: {
|
||||
responsive: {
|
||||
widths: [300, 600, 900, 1200, 1640],
|
||||
sizes: '(min-width: 1024px) 820px, calc(100vw - 20px)',
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<inline-notification type="tip">
|
||||
|
||||
As an end user in most cases you don't want to mess with this as a layout preset should set this for you. If you are building your own layout preset then be sure to set `widths` and `sizes` via `adjustImagePresets`
|
||||
|
||||
```js
|
||||
export function myPreset() {
|
||||
return {
|
||||
adjustImagePresets: imagePresets => ({
|
||||
...imagePresets,
|
||||
responsive: {
|
||||
...imagePresets.responsive,
|
||||
widths: [600, 900, 1640],
|
||||
sizes: '(min-width: 1024px) 820px, calc(100vw - 40px)',
|
||||
},
|
||||
}),
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
</inline-notification>
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/10--configuration/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () =>
|
||||
html`<h1>Configuration</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,110 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/20--presets/10--joining-blocks.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Joining Blocks
|
||||
|
||||
The template system allows for a very granular control of how individual parts will be merged, overwritten or reorderd.
|
||||
|
||||
As a preset you may want to add this to your layout.
|
||||
|
||||
{% raw %}
|
||||
|
||||
```jinja2
|
||||
<footer id="main-footer">
|
||||
{% for blockName, blockPath in _joiningBlocks.footer %}
|
||||
{% include blockPath %}
|
||||
{% endfor %}
|
||||
</footer>
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
This will now render all templates within `_includes/_joiningBlocks/footer/*`.
|
||||
|
||||
## Adding content without overriding
|
||||
|
||||
Let's assume we have a preset with the following files
|
||||
|
||||
👉 `_includes/_joiningBlocks/footer/10-first.njk`
|
||||
|
||||
```html
|
||||
<p>first</p>
|
||||
```
|
||||
|
||||
👉 `_includes/_joiningBlocks/footer/20-second.njk`
|
||||
|
||||
```html
|
||||
<p>second</p>
|
||||
```
|
||||
|
||||
And it produces this in your website
|
||||
|
||||
```html
|
||||
<footer>
|
||||
<p>first</p>
|
||||
<p>second</p>
|
||||
</footer>
|
||||
```
|
||||
|
||||
Now we can add a file which will insert content without needing to overwrite any of the preset file.
|
||||
|
||||
👉 `docs/_includes/_joiningBlocks/footer/15-in-between.njk`
|
||||
|
||||
```html
|
||||
<p>in-between</p>
|
||||
```
|
||||
|
||||
the final output will be
|
||||
|
||||
```html
|
||||
<footer>
|
||||
<p>first</p>
|
||||
<p>in-between</p>
|
||||
<p>second</p>
|
||||
</footer>
|
||||
```
|
||||
|
||||
## Overriding Content
|
||||
|
||||
Now if you want to overwrite you can use the same filename.
|
||||
|
||||
👉 `docs/_includes/_joiningBlocks/footer/10-first.njk`
|
||||
|
||||
```html
|
||||
<p>updated first</p>
|
||||
```
|
||||
|
||||
the final output will be
|
||||
|
||||
```html
|
||||
<footer>
|
||||
<p>updated first</p>
|
||||
<p>second</p>
|
||||
</footer>
|
||||
```
|
||||
|
||||
## Reordering and Overriding
|
||||
|
||||
Sometimes you wanna reorder when you overwrite as well
|
||||
|
||||
👉 `docs/_includes/_joiningBlocks/footer/30-first.njk`
|
||||
|
||||
```html
|
||||
<p>first</p>
|
||||
```
|
||||
|
||||
the final output will be
|
||||
|
||||
```html
|
||||
<footer>
|
||||
<p>second</p>
|
||||
<p>first</p>
|
||||
</footer>
|
||||
```
|
||||
|
||||
Note: Reordering always requires you to overwrite as well.
|
||||
@@ -1,10 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/20--presets/20--launch/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () =>
|
||||
html`<h1>Launch</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,155 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/20--presets/20--launch/overview.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
```js server
|
||||
import { html } from 'lit-html';
|
||||
```
|
||||
|
||||
# Overview
|
||||
|
||||
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
|
||||
|
||||
Install `@rocket/launch` from the NPM repository using your favourite package manager.
|
||||
|
||||
<code-tabs collection="package-managers" default-tab="npm" align="end">
|
||||
|
||||
```bash tab npm
|
||||
npm i @rocket/launch
|
||||
```
|
||||
|
||||
```bash tab yarn
|
||||
yarn add @rocket/launch
|
||||
```
|
||||
|
||||
```bash tab pnpm
|
||||
pnpm add @rocket/launch
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
## Usage
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
```js
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
presets: [rocketLaunch()],
|
||||
};
|
||||
```
|
||||
|
||||
## Data
|
||||
|
||||
You can define your own data for the available Layouts.
|
||||
|
||||
## Inline Notification
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
|
||||
Launch ships with `<inline-notification>`, a custom element that applies some styles similar to "info boxes". The element works for `<noscript>` users as well, as long as you don't [override](/guides/presets/overriding/) the default `noscript.css` file.
|
||||
|
||||
To add an inline notification you need to remember to import the element definition:
|
||||
|
||||
````md
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
````
|
||||
|
||||
Then you can add your notification to the page. If you want to write the notification's content using markdown, just pad the opening and closing tags with empty lines.
|
||||
|
||||
There are three varieties of `<inline-notification>`, "tip", "warning", and "danger"
|
||||
|
||||
<style>
|
||||
#inline-notifications::part(tab) {
|
||||
text-transform: capitalize;
|
||||
}
|
||||
#inline-notifications code-tab::part(content) {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 6px;
|
||||
}
|
||||
#inline-notifications code-copy::part(copy-button) {
|
||||
position: absolute;
|
||||
top: 10px;
|
||||
border-radius: 6px;
|
||||
border: 1px solid var(--primary-lines-color);
|
||||
}
|
||||
</style>
|
||||
|
||||
<inline-notification type="tip">
|
||||
|
||||
Take a tip from me
|
||||
|
||||
</inline-notification>
|
||||
|
||||
```md
|
||||
<inline-notification type="tip">
|
||||
|
||||
Take a tip from me
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
|
||||
<inline-notification type="warning">
|
||||
|
||||
Be _sure_ about this...
|
||||
|
||||
</inline-notification>
|
||||
|
||||
```md
|
||||
<inline-notification type="warning">
|
||||
|
||||
Be _sure_ about this...
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
|
||||
<inline-notification type="danger">
|
||||
|
||||
You **really** shouldn't!
|
||||
|
||||
</inline-notification>
|
||||
|
||||
```md
|
||||
<inline-notification type="danger">
|
||||
|
||||
You **really** shouldn't!
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
|
||||
### Modify the Title
|
||||
|
||||
The notification title defaults to it's type. You can write a custom title with the `title` attribute.
|
||||
|
||||
<inline-notification type="tip" title="success">
|
||||
|
||||
I am a success message
|
||||
|
||||
</inline-notification>
|
||||
|
||||
```md
|
||||
<inline-notification type="tip" title="success">
|
||||
|
||||
I am a success message
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
|
||||
<inline-notification type="warning">
|
||||
|
||||
The `title` attribute does not change the title for `<noscript>` users, so don't include any critical information in it.
|
||||
|
||||
</inline-notification>
|
||||
@@ -1,10 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/20--presets/30--search/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () =>
|
||||
html`<h1>Search</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,42 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/20--presets/30--search/overview.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Overview
|
||||
|
||||
Add a search for all your static content.
|
||||
|
||||
## Installation
|
||||
|
||||
<code-tabs collection="package-managers" default-tab="npm" align="end">
|
||||
|
||||
```bash tab npm
|
||||
npm i @rocket/search
|
||||
```
|
||||
|
||||
```bash tab yarn
|
||||
yarn add @rocket/search
|
||||
```
|
||||
|
||||
```bash tab pnpm
|
||||
pnpm add @rocket/search
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
## Usage
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
```js
|
||||
import { rocketSearch } from '@rocket/search';
|
||||
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
presets: [rocketSearch()],
|
||||
};
|
||||
```
|
||||
@@ -1,42 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/20--presets/40--blog.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Blog
|
||||
|
||||
Enable writing blog posts within your Rocket site.
|
||||
|
||||
## Installation
|
||||
|
||||
<code-tabs collection="package-managers" default-tab="npm" align="end">
|
||||
|
||||
```bash tab npm
|
||||
npm i @rocket/blog
|
||||
```
|
||||
|
||||
```bash tab yarn
|
||||
yarn add @rocket/blog
|
||||
```
|
||||
|
||||
```bash tab pnpm
|
||||
pnpm add @rocket/blog
|
||||
```
|
||||
|
||||
</code-tabs>
|
||||
|
||||
## Usage
|
||||
|
||||
👉 `rocket.config.js`
|
||||
|
||||
```js
|
||||
import { rocketBlog } from '@rocket/blog';
|
||||
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default {
|
||||
presets: [rocketBlog()],
|
||||
};
|
||||
```
|
||||
@@ -1,10 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/20--presets/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () =>
|
||||
html`<h1>Presets</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,239 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/30--markdown-javascript/20--preview.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Preview
|
||||
|
||||
You can showcase live running code by annotating a code block with `js preview-story`.
|
||||
|
||||
## Features
|
||||
|
||||
- Shows components inside the page as they are
|
||||
- You can enable “Simulation Mode” to break them out
|
||||
- Simulation mode renders in an iframe to supporting media queries and isolated Simulation settings
|
||||
- Simulation Settings
|
||||
- Style (windows, mac, android, iOS)
|
||||
- Size (small, medium, large, Galaxy S5, iPhone X, iPad …)
|
||||
- Automatic Height
|
||||
- Theme (light, dark)
|
||||
- Language (en, nl, …)
|
||||
- Settings are ”global” for all Simulators (e.g. changing one will change all)
|
||||
- Settings can be remembered for other pages / return visits
|
||||
|
||||
```js script
|
||||
import { html } from '@mdjs/mdjs-preview';
|
||||
import './assets/demo-element.js';
|
||||
```
|
||||
|
||||
## JavaScript Story
|
||||
|
||||
````md
|
||||
```js script
|
||||
import { html } from '@mdjs/mdjs-preview';
|
||||
import './assets/demo-element.js';
|
||||
```
|
||||
|
||||
```js preview-story
|
||||
export const foo = () => html`<demo-element></demo-element>`;
|
||||
```
|
||||
````
|
||||
|
||||
will result in
|
||||
|
||||
```js preview-story
|
||||
export const foo = () => html` <demo-element></demo-element> `;
|
||||
```
|
||||
|
||||
```js story-code
|
||||
// not defined for android
|
||||
```
|
||||
|
||||
```js story-code
|
||||
// not defined for ios
|
||||
```
|
||||
|
||||
#### Story Code
|
||||
|
||||
If your preview is followed by a code blocks marked as `story-code` then those will be shown when switching between multiple platforms
|
||||
|
||||
````md
|
||||
```js preview-story
|
||||
// will be visible when platform web is selected
|
||||
export const JsPreviewStory = () => html` <demo-element></demo-element> `;
|
||||
```
|
||||
|
||||
```xml story-code
|
||||
<!-- will be visible when platform android is selected -->
|
||||
<Button
|
||||
android:id="@+id/demoElement"
|
||||
android:layout_width="wrap_content"
|
||||
android:layout_height="wrap_content"
|
||||
android:text="Android Code"
|
||||
style="@style/Widget.Demo.Element"
|
||||
/>
|
||||
```
|
||||
|
||||
```swift story-code
|
||||
// will be visible when platform ios is selected
|
||||
import Demo.Element
|
||||
|
||||
let card = DemoElement()
|
||||
```
|
||||
````
|
||||
|
||||
See it in action by opening up the code block and switching platforms
|
||||
|
||||
```js preview-story
|
||||
// will be visible when platform web is selected
|
||||
export const JsPreviewStory = () => html` <demo-element></demo-element> `;
|
||||
```
|
||||
|
||||
```xml story-code
|
||||
<!-- will be visible when platform android is selected -->
|
||||
<Button
|
||||
android:id="@+id/demoElement"
|
||||
android:layout_width="wrap_content"
|
||||
android:layout_height="wrap_content"
|
||||
android:text="Android Code"
|
||||
style="@style/Widget.Demo.Element"
|
||||
/>
|
||||
```
|
||||
|
||||
```swift story-code
|
||||
// will be visible when platform ios is selected
|
||||
import Demo.Element
|
||||
|
||||
let card = DemoElement()
|
||||
```
|
||||
|
||||
## HTML Story
|
||||
|
||||
````md
|
||||
```html preview-story
|
||||
<demo-element></demo-element>
|
||||
```
|
||||
````
|
||||
|
||||
will result in
|
||||
|
||||
```html preview-story
|
||||
<demo-element></demo-element>
|
||||
```
|
||||
|
||||
## Setup Simulation Mode
|
||||
|
||||
For simulation mode we need a dedicated html file that will be used as an iframe target while loading stories.
|
||||
|
||||
The fastest way to create such a file is to use the `layout-simulator` layout.
|
||||
|
||||
Create a file `docs/simulator.md` with the following content.
|
||||
|
||||
```md
|
||||
---
|
||||
layout: layout-simulator
|
||||
eleventyExcludeFromCollections: true
|
||||
excludeFromSearch: true
|
||||
---
|
||||
```
|
||||
|
||||
Once you have that you need to configure it for the story renderer by setting it in your `rocket.config.js`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default ({
|
||||
setupUnifiedPlugins: [
|
||||
adjustPluginOptions('mdjsSetupCode', {
|
||||
simulationSettings: { simulatorUrl: '/simulator/' },
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<inline-notification type="tip">
|
||||
|
||||
You can freely choose the path for the "simulator" by creating the md file in a different folder and adjusting the path in the config.
|
||||
|
||||
</inline-notification>
|
||||
|
||||
## Simulator states
|
||||
|
||||
To simulate these stats that usually come from the device itself we put those infos on the document tag.
|
||||
|
||||
We can simulate the following settings
|
||||
|
||||
1. `platform`
|
||||
Adopting styles and behavior depending on which device platform you are.
|
||||
```html
|
||||
<html platform="web"></html>
|
||||
<html platform="android"></html>
|
||||
<html platform="ios"></html>
|
||||
<!-- potentially later -->
|
||||
<html platform="web-windows"></html>
|
||||
<html platform="web-mac"></html>
|
||||
```
|
||||
2. `theme`
|
||||
Adjust your styles based on a theme - light/dark are the default but you can add as many as you want.
|
||||
```html
|
||||
<html theme="light"></html>
|
||||
<html theme="dark"></html>
|
||||
```
|
||||
3. `language`
|
||||
Best to relay on `data-lang` as `lang` often gets changes by translations services which may interfere with your translation loading system.
|
||||
```html
|
||||
<html lang="en-US" data-lang="en-US"></html>
|
||||
<html lang="de-DE" data-lang="de-DE"></html>
|
||||
```
|
||||
|
||||
If you want to react to such document changes you can use an [MutationObserver](https://developer.mozilla.org/de/docs/Web/API/MutationObserver).
|
||||
|
||||
For a vanilla web component it could look something like this:
|
||||
|
||||
```js
|
||||
class DemoElement extends HTMLElement {
|
||||
constructor() {
|
||||
super();
|
||||
this.attachShadow({ mode: 'open' });
|
||||
|
||||
this.platform = 'the web';
|
||||
this.language = 'en-US';
|
||||
this.theme = 'light';
|
||||
|
||||
this.observer = new MutationObserver(this.updateData);
|
||||
}
|
||||
|
||||
updateData = () => {
|
||||
this.platform = document.documentElement.getAttribute('platform') || 'the web';
|
||||
this.language = document.documentElement.getAttribute('data-lang') || 'en-US';
|
||||
this.theme = document.documentElement.getAttribute('theme') || 'light';
|
||||
this.requestUpdate();
|
||||
};
|
||||
|
||||
connectedCallback() {
|
||||
this.updateData();
|
||||
|
||||
this.observer.observe(document.documentElement, { attributes: true });
|
||||
}
|
||||
|
||||
requestUpdate() {
|
||||
this.shadowRoot.innerHTML = this.render();
|
||||
}
|
||||
|
||||
render() {
|
||||
return `
|
||||
...
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
customElements.define('demo-element', DemoElement);
|
||||
```
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
@@ -1,31 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/30--markdown-javascript/30--story.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Story
|
||||
|
||||
You can showcase live running code by annotating a code block with `js story`.
|
||||
|
||||
```js script
|
||||
import { html } from '@mdjs/mdjs-story';
|
||||
```
|
||||
|
||||
````md
|
||||
```js script
|
||||
import { html } from '@mdjs/mdjs-story';
|
||||
```
|
||||
|
||||
```js story
|
||||
export const foo = () => html` <p>my html</p> `;
|
||||
```
|
||||
````
|
||||
|
||||
will result in
|
||||
|
||||
```js story
|
||||
export const foo = () => html` <p>my html</p> `;
|
||||
```
|
||||
@@ -1,69 +0,0 @@
|
||||
class DemoElement extends HTMLElement {
|
||||
constructor() {
|
||||
super();
|
||||
this.attachShadow({ mode: 'open' });
|
||||
|
||||
this.platform = 'the web';
|
||||
this.language = 'en-US';
|
||||
this.theme = 'light';
|
||||
|
||||
this.observer = new MutationObserver(this.updateData);
|
||||
}
|
||||
|
||||
updateData = () => {
|
||||
this.platform = document.documentElement.getAttribute('platform') || 'the web';
|
||||
this.language = document.documentElement.getAttribute('data-lang') || 'en-US';
|
||||
this.theme = document.documentElement.getAttribute('theme') || 'light';
|
||||
this.requestUpdate();
|
||||
};
|
||||
|
||||
connectedCallback() {
|
||||
this.updateData();
|
||||
|
||||
this.observer.observe(document.documentElement, { attributes: true });
|
||||
}
|
||||
|
||||
requestUpdate() {
|
||||
this.shadowRoot.innerHTML = this.render();
|
||||
}
|
||||
|
||||
render() {
|
||||
return `
|
||||
<style>
|
||||
:host {
|
||||
display: block;
|
||||
background: var(--demo-background-color);
|
||||
color: var(--demo-color);
|
||||
padding: 10px;
|
||||
}
|
||||
|
||||
:host[platform~="web"] {
|
||||
border-bottom: 2px solid #333;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 640px) {
|
||||
.about {
|
||||
display: flex;
|
||||
}
|
||||
.about ul {
|
||||
width: 50%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
<p>Hello I am DemoElement 👋</p>
|
||||
<div class="about">
|
||||
<ul>
|
||||
<li>My purpose is to demonstrate how an element can adopt to different environments</li>
|
||||
<li>I like <strong>${this.platform}</strong></li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li>My mother languages is <strong>${this.language}</strong></li>
|
||||
<li>I feel very comfortable in the <strong>${this.theme}</strong></li>
|
||||
</ul>
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
customElements.define('demo-element', DemoElement);
|
||||
@@ -1,10 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/30--markdown-javascript/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () =>
|
||||
html`<h1>Markdown Javascript</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,391 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/50--tools/10--plugins-manager.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Plugins Manager
|
||||
|
||||
The Plugins Manager replaces the specific registration/execution (with options) in a given plugin system by an intend to use a plugin (with these options).
|
||||
This allows your users to adjust the options before actually applying the plugins.
|
||||
|
||||
## Setup
|
||||
|
||||
1. Install npm package
|
||||
```bash
|
||||
npm i plugins-manager
|
||||
```
|
||||
2. Change your public API from an array of plugin "instances" to an array of setup functions
|
||||
```diff
|
||||
import myPlugin from 'my-plugin';
|
||||
+ import { addPlugin } from 'plugins-manager';
|
||||
export default {
|
||||
- plugins: [myPlugin],
|
||||
+ setupPlugins: [addPlugin(myPlugin)]
|
||||
}
|
||||
```
|
||||
3. Convert setup function to plugins
|
||||
|
||||
```js
|
||||
import { applyPlugins } from 'plugins-manager';
|
||||
|
||||
const finalConfig = applyPlugins(config); // "converts" setupPlugins to plugins
|
||||
|
||||
// work with plugins or pass it on to another tool
|
||||
const bundle = await rollup(finalConfig);
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
As you users in most cases you will need to either add or adjust a given plugin in a config file.
|
||||
|
||||
👉 `my-tool.config.js`
|
||||
|
||||
```js
|
||||
import { addPlugin, adjustPluginOptions } from 'plugins-manager';
|
||||
import json from '@rollup/plugin-json';
|
||||
import { nodeResolve } from '@rollup/plugin-node-resolve';
|
||||
|
||||
export default {
|
||||
setupPlugins: [
|
||||
// add a new plugin with optional plugin options
|
||||
addPlugin(json, {
|
||||
/* ... */
|
||||
}),
|
||||
|
||||
// adjust the options of a plugin that is already registered
|
||||
adjustPluginOptions(nodeResolve, {
|
||||
/* ... */
|
||||
}),
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Plugins can be functions or classes
|
||||
|
||||
### Function Plugins
|
||||
|
||||
```js
|
||||
function myPlugin({ lastName: 'initial-second' }) {
|
||||
// ...
|
||||
}
|
||||
|
||||
export default {
|
||||
setupPlugins: [addPlugin(myPlugin)],
|
||||
};
|
||||
|
||||
// function parameters are type safe
|
||||
addPlugin(myPlugin, { lastName: 'new name' }); // ts ok
|
||||
addPlugin(myPlugin, { otherProp: 'new name' }); // ts error
|
||||
```
|
||||
|
||||
### Class Plugins
|
||||
|
||||
The options are passed to the constructor.
|
||||
|
||||
```js
|
||||
/**
|
||||
* @typedef {object} MyClassOptions
|
||||
* @property {string} lastName
|
||||
*/
|
||||
|
||||
class MyClass {
|
||||
/** @type {MyClassOptions} */
|
||||
options = {
|
||||
lastName: 'initial-second',
|
||||
};
|
||||
|
||||
/**
|
||||
* @param {Partial<MyClassOptions>} options
|
||||
*/
|
||||
constructor(options = {}) {
|
||||
this.options = { ...this.options, ...options };
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default {
|
||||
setupPlugins: [addPlugin(MyClass)],
|
||||
};
|
||||
|
||||
// constructor parameters are type safe
|
||||
addPlugin(MyClass, { lastName: 'new name' }); // ts ok
|
||||
addPlugin(MyClass, { otherProp: 'new name' }); // ts error
|
||||
```
|
||||
|
||||
## Problem
|
||||
|
||||
Many plugin systems require you to either execute a plugin function like in `rollup`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
import json from '@rollup/plugin-json';
|
||||
|
||||
/** @type {import('rocket/cli').RocketCliConfig} */
|
||||
export default ({
|
||||
plugins: [json({ preferConst: true })],
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
or add it in a special way like in `eleventy`
|
||||
|
||||
```js
|
||||
const pluginSyntaxHighlight = require('@11ty/eleventy-plugin-syntaxhighlight');
|
||||
module.exports = function (eleventyConfig) {
|
||||
eleventyConfig.addPlugin(pluginSyntaxHighlight, { templateFormats: ['md'] });
|
||||
};
|
||||
```
|
||||
|
||||
or `unified/remark`.
|
||||
|
||||
```js
|
||||
var unified = require('unified');
|
||||
var markdown = require('remark-parse');
|
||||
var toc = require('remark-toc');
|
||||
|
||||
var processor = unified().use(markdown).use(toc, { maxDepth: 2 });
|
||||
// ...
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
This means if you wish to define default plugins and allow your user to override all of the settings it's "impossible".
|
||||
|
||||
## Solution
|
||||
|
||||
The plugins manager lets you orchestrate a set of "meta plugins" which are defined by
|
||||
|
||||
- plugin (class or function)
|
||||
- it's options
|
||||
|
||||
```js
|
||||
import beep from '@rollup/plugin-beep';
|
||||
import url from '@rollup/plugin-url';
|
||||
|
||||
let metaPlugins = [{ plugin: beep }, { plugin: url, options: { limit: 10000 } }];
|
||||
```
|
||||
|
||||
This array can be modified by adding/removing or adjusting options.
|
||||
|
||||
```js
|
||||
// raw add
|
||||
metaPlugins.push({
|
||||
// another plugin
|
||||
});
|
||||
|
||||
// raw adjust
|
||||
metaPlugins[1].options.limit = 20000;
|
||||
```
|
||||
|
||||
And then you can convert it into the specific format that can be assigned to your system in question.
|
||||
|
||||
```js
|
||||
// execute plugins for rollup
|
||||
const plugins = metaPlugins.map(pluginObj => {
|
||||
if (pluginObj.options) {
|
||||
return pluginObj.plugin(pluginObj.options);
|
||||
} else {
|
||||
return pluginObj.plugin();
|
||||
}
|
||||
});
|
||||
|
||||
// rollup.config.js
|
||||
export default {
|
||||
plugins,
|
||||
};
|
||||
```
|
||||
|
||||
### Adding Helpers
|
||||
|
||||
Doing array manipulations is kinda error-prone so we encourage to use an array of setup function. Where as each setup function can either add a new plugin (with a unique name) or adjust an already existing plugin.
|
||||
|
||||
```js
|
||||
import { addPlugin, adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
const systemSetupFunctions = [addPlugin(first), addPlugin(second)];
|
||||
const userSetupFunctions = [adjustPluginOptions(first, { my: 'options' })];
|
||||
```
|
||||
|
||||
Arrays of functions can by merged like so
|
||||
|
||||
```js
|
||||
const finalSetupFunctions = [...systemSetupFunctions, ...userSetupFunctions];
|
||||
```
|
||||
|
||||
and then converted to the final output.
|
||||
|
||||
```js
|
||||
import { applyPlugins } from 'plugins-manager';
|
||||
|
||||
const plugins = applyPlugins(finalSetupFunctions, metaPlugins);
|
||||
```
|
||||
|
||||
## Adding a Plugin
|
||||
|
||||
This makes sure that
|
||||
|
||||
- the name is unique
|
||||
- you can add at at `top`, `bottom` and `after/before` a given other plugin
|
||||
|
||||
By default it adds at the bottom.
|
||||
|
||||
```js
|
||||
import json from '@rollup/plugin-json';
|
||||
import { addPlugin } from 'plugins-manager';
|
||||
|
||||
const userSetupFunctions = [addPlugin(json, { preferConst: true })];
|
||||
```
|
||||
|
||||
Example usage:
|
||||
|
||||
```js
|
||||
addPlugin(json); // Add at the bottom (default)
|
||||
addPlugin(json, {}, { location: 'top' }); // Add at the top/beginning of the array
|
||||
addPlugin(json, {}, { location: beep }); // Add after (default) plugin 'beep'
|
||||
addPlugin(json, {}, { location: beep, how: 'before' }); // Add before plugin 'beep'
|
||||
```
|
||||
|
||||
This is type safe and typescript will throw an error if you pass the wrong type.
|
||||
|
||||
```js
|
||||
function myPlugin({ myFlag = false } = {}) {
|
||||
// ...
|
||||
}
|
||||
|
||||
addPlugin(myPlugin, { myFlag: true }); // ts ok
|
||||
addPlugin(myPlugin, { notExisting: true }); // ts error
|
||||
```
|
||||
|
||||
## Adjusting Plugin Options
|
||||
|
||||
Adjusting options means to either
|
||||
|
||||
- flatly merge objects (e.g. only the first level will be preserved)
|
||||
- calling a function to do the merge yourself
|
||||
- setting the raw value (if not an object or function)
|
||||
- you need to have a reference to the plugin (which is used to auto complete the available options via typescript)
|
||||
|
||||
```js
|
||||
import json from '@rollup/plugin-json';
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
const userSetupFunctions = [
|
||||
adjustPluginOptions(json, { preferConst: false, anotherOption: 'format' }),
|
||||
];
|
||||
```
|
||||
|
||||
Example usage:
|
||||
|
||||
```js
|
||||
// given
|
||||
addPlugin(json, {
|
||||
other: {
|
||||
nested: 'other.nested',
|
||||
nested2: 'other.nested2',
|
||||
},
|
||||
main: true,
|
||||
});
|
||||
|
||||
// merge objects flately
|
||||
adjustPluginOptions(json, { other: { nested: '--overwritten--' } });
|
||||
// resulting options = { other: { nested: '--overwritten--' }, main: true }
|
||||
// NOTE: nested2 is removed
|
||||
|
||||
// merge via function
|
||||
adjustPluginOptions(json, config => ({ other: { ...config.other, nested: '--overwritten--' } }));
|
||||
// resulting options = { other: { nested: '--overwritten--', nested2: 'other.nested2' }, main: true }
|
||||
|
||||
// merge via function to override full options
|
||||
adjustPluginOptions(json, config => ({ only: 'this' }));
|
||||
// resulting options = { only: 'this' }
|
||||
|
||||
// setting a raw value
|
||||
adjustPluginOptions(json, false);
|
||||
// resulting options = false
|
||||
```
|
||||
|
||||
This is type safe and typescript will throw an error if you pass the wrong type.
|
||||
|
||||
```js
|
||||
function myPlugin({ myFlag = false } = {}) {
|
||||
// ...
|
||||
}
|
||||
|
||||
adjustPluginOptions(myPlugin, { myFlag: true }); // ts ok
|
||||
adjustPluginOptions(myPlugin, { notExisting: true }); // ts error
|
||||
```
|
||||
|
||||
## Remove Plugin
|
||||
|
||||
Sometimes you would like to remove a default plugin from the config.
|
||||
|
||||
```js
|
||||
export default {
|
||||
setupPlugins: [removePlugin(json)],
|
||||
};
|
||||
```
|
||||
|
||||
## Converting metaPlugins to an Actual Plugin
|
||||
|
||||
To execute all setup function you can use this little helper
|
||||
|
||||
```js
|
||||
const finalMetaPlugins = executeSetupFunctions(finalSetupFunctions, metaPlugins);
|
||||
```
|
||||
|
||||
And then you can convert it into your format.
|
||||
For Rollup you would execute the plugin with the options if there are any.
|
||||
|
||||
```js
|
||||
const plugins = finalMetaPlugins.map(pluginObj => {
|
||||
if (pluginObj.options) {
|
||||
return pluginObj.plugin(pluginObj.options);
|
||||
} else {
|
||||
return pluginObj.plugin();
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
Rollup has a more specific helper that handles
|
||||
|
||||
- `config.setupPlugins`
|
||||
|
||||
Note: if you provide `config.plugins` then it will return that directly ignoring `setupPlugins`
|
||||
|
||||
```js
|
||||
import { applyPlugins } from 'plugins-manager';
|
||||
|
||||
const finalConfig = applyPlugins(currentConfig, defaultMetaPlugins);
|
||||
```
|
||||
|
||||
Eleventy
|
||||
|
||||
```js
|
||||
module.exports = eleventyConfig => {
|
||||
for (const pluginObj of metaPlugins) {
|
||||
if (pluginObj.options) {
|
||||
eleventyConfig.addPlugin(pluginObj.plugin, pluginObj.options);
|
||||
} else {
|
||||
eleventyConfig.addPlugin(pluginObj.plugin);
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
Unified/Remark
|
||||
|
||||
```js
|
||||
const parser = unified();
|
||||
|
||||
for (const pluginObj of metaPlugins) {
|
||||
parser.use(pluginObj.plugin, pluginObj.options);
|
||||
}
|
||||
```
|
||||
@@ -1,71 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/50--tools/30--check-html-links.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Check HTML Links
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
|
||||
A fast checker for broken links/references in HTML.
|
||||
|
||||
<inline-notification type="tip">
|
||||
|
||||
Read the [Introducing Check HTML Links - no more bad links](../../blog/introducing-check-html-links.md) Blog post to find out how it came to be and how it works.
|
||||
|
||||
</inline-notification>
|
||||
|
||||
## Features
|
||||
|
||||
- Checks all html files for broken local links/references (in href, src, srcset)
|
||||
- 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
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
npm i -D check-html-links
|
||||
```
|
||||
|
||||
## CLI flags
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------------- | ------- | --------------------------------------------------------------------------------------------------- |
|
||||
| root-dir | string | the root directory to serve files from. Defaults to the current working directory |
|
||||
| ignore-link-pattern | string | do not check links matching the pattern |
|
||||
| continue-on-error | boolean | if present it will not exit with an error code - useful while writing or for temporary passing a ci |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# check a folder _site
|
||||
npx check-html-links _site
|
||||
|
||||
# ignore all links like <a href="/users/123">
|
||||
npx check-html-links _site --ignore-link-pattern "/users/*" "/users/**/*"
|
||||
|
||||
# ignore all links like <a href="/users/123"> & <a href="/users/123/details">
|
||||
npx check-html-links _site --ignore-link-pattern "/users/*" "/users/**/*"
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
|
||||
|
||||
## 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)
|
||||
|
||||
| Tool | Lines printed | Times | Lang | Dependency Tree |
|
||||
| ---------------- | ------------- | ------ | ---- | --------------- |
|
||||
| check-html-links | 38 | ~2.5s | node | 19 |
|
||||
| link-checker | 3000+ | ~11s | node | 106 |
|
||||
| hyperlink | 68 | 4m 20s | node | 481 |
|
||||
| htmltest | 1000+ | ~0.7s | GO | - |
|
||||
@@ -1,10 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/50--tools/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
export default () =>
|
||||
html`<h1>Tools</h1>
|
||||
<meta name="menu:exclude" content="true" />`;
|
||||
@@ -1,36 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/index.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
<meta name="menu:link.text" content="Docs" />
|
||||
|
||||
# Documentation
|
||||
|
||||
Here you will find all the details for each of the packages/systems we offer.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Configuration](./configuration/)
|
||||
- [Overview](./configuration/overview/)
|
||||
- [Computed Config](./configuration/computed-config/)
|
||||
- [Service Worker](./configuration/service-worker/)
|
||||
- [Images](./configuration/images/)
|
||||
- [Presets](./presets/)
|
||||
- [Joining Blocks](./presets/joining-blocks/)
|
||||
- [`@rocket/launch`](./presets/launch/)
|
||||
- [`@rocket/search`](./presets/search/)
|
||||
- [`@rocket/blog`](./presets/blog/)
|
||||
- [Markdown JavaScript](./markdown-javascript/)
|
||||
- [Overview](./markdown-javascript/overview/)
|
||||
- [Preview](./markdown-javascript/preview/)
|
||||
- [Story](./markdown-javascript/story/)
|
||||
- [Eleventy Plugins](./eleventy-plugins/)
|
||||
- [Markdown JavaScript (mdjs)](./eleventy-plugins/mdjs-unified/)
|
||||
- [Tools](./tools/)
|
||||
- [Plugins Manager](./tools/plugins-manager/)
|
||||
- [Rollup Config](./tools/rollup-config/)
|
||||
- [Check HTML Links ](./tools/check-html-links/)
|
||||
@@ -1,15 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '30--blog/index.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { html } from 'lit-html';
|
||||
|
||||
export default () => html`
|
||||
<h1>Rocket Blog</h1>
|
||||
<meta name="menu:link.text" content="Blog" />
|
||||
<p>
|
||||
Discover articles from the core team and contributors about Rocket, tips and tricks included!
|
||||
</p>
|
||||
`;
|
||||
@@ -1,11 +0,0 @@
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '404.html.rocket.js';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu } from './recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
import { Layout404 } from '@rocket/launch';
|
||||
|
||||
export const layout = new Layout404();
|
||||
|
||||
export default () => '';
|
||||
4
docs/404.md
Normal file
4
docs/404.md
Normal file
@@ -0,0 +1,4 @@
|
||||
---
|
||||
layout: 404.njk
|
||||
permalink: 404.html
|
||||
---
|
||||
9
docs/_assets/head.html
Normal file
9
docs/_assets/head.html
Normal file
@@ -0,0 +1,9 @@
|
||||
<link
|
||||
href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;700&display=swap"
|
||||
rel="stylesheet"
|
||||
/>
|
||||
<link
|
||||
href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;700&display=swap"
|
||||
rel="stylesheet"
|
||||
/>
|
||||
<meta name="twitter:creator" content="@modern_web_dev" />
|
||||
1
docs/_assets/home-background-original.svg
Normal file
1
docs/_assets/home-background-original.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 12 KiB |
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
|
Before Width: | Height: | Size: 2.5 KiB After Width: | Height: | Size: 2.5 KiB |
|
Before Width: | Height: | Size: 51 KiB After Width: | Height: | Size: 51 KiB |
21
docs/_assets/style.css
Normal file
21
docs/_assets/style.css
Normal file
@@ -0,0 +1,21 @@
|
||||
body[layout='home'] .markdown-body .call-to-action:nth-of-type(2) {
|
||||
--primary-color: #222;
|
||||
--primary-color-lighter: #333;
|
||||
--primary-color-darker: #000;
|
||||
}
|
||||
|
||||
@media screen and (min-width: 1024px) {
|
||||
body[layout='home'][home-layout='background'] .page-background {
|
||||
top: -210px;
|
||||
right: -463px;
|
||||
transform: rotate(45deg);
|
||||
}
|
||||
}
|
||||
|
||||
rocket-navigation {
|
||||
font-family: 'Montserrat', sans-serif;
|
||||
}
|
||||
|
||||
header {
|
||||
font-family: 'Montserrat', sans-serif;
|
||||
}
|
||||
29
docs/_assets/webmanifest.json
Normal file
29
docs/_assets/webmanifest.json
Normal file
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"name": "Rocket",
|
||||
"short_name": "rocket",
|
||||
"theme_color": "#e63946",
|
||||
"background_color": "#1d3557",
|
||||
"display": "standalone",
|
||||
"orientation": "portrait",
|
||||
"Scope": "/",
|
||||
"start_url": "/",
|
||||
"icons": [
|
||||
{
|
||||
"src": "../_merged_assets/_static/icons/android-chrome-192x192.png",
|
||||
"sizes": "128x128",
|
||||
"type": "image/png"
|
||||
},
|
||||
{
|
||||
"src": "../_merged_assets/_static/icons/android-chrome-512x512.png",
|
||||
"sizes": "512x512",
|
||||
"type": "image/png"
|
||||
},
|
||||
{
|
||||
"src": "../_merged_assets/_static/icons/maskable-icon.jpg",
|
||||
"sizes": "1024x1024",
|
||||
"type": "image/jpg",
|
||||
"purpose": "any maskable"
|
||||
}
|
||||
],
|
||||
"splash_pages": null
|
||||
}
|
||||
45
docs/_data/footer.json
Normal file
45
docs/_data/footer.json
Normal file
@@ -0,0 +1,45 @@
|
||||
[
|
||||
{
|
||||
"name": "Discover",
|
||||
"children": [
|
||||
{
|
||||
"text": "Blog",
|
||||
"href": "/blog/"
|
||||
},
|
||||
{
|
||||
"text": "Help and Feedback",
|
||||
"href": "https://github.com/modernweb-dev/rocket/issues"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "Follow",
|
||||
"children": [
|
||||
{
|
||||
"text": "Github",
|
||||
"href": "https://github.com/modernweb-dev/rocket"
|
||||
},
|
||||
{
|
||||
"text": "Twitter",
|
||||
"href": "https://twitter.com/modern_web_dev"
|
||||
},
|
||||
{
|
||||
"text": "Slack",
|
||||
"href": "/about/slack/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "Support",
|
||||
"children": [
|
||||
{
|
||||
"text": "Sponsor",
|
||||
"href": "/about/sponsor/"
|
||||
},
|
||||
{
|
||||
"text": "Contribute",
|
||||
"href": "https://github.com/modernweb-dev/rocket/blob/main/CONTRIBUTING.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
4
docs/_data/rocketLaunch.json
Normal file
4
docs/_data/rocketLaunch.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"homeLayout": "background",
|
||||
"newsletter": false
|
||||
}
|
||||
23
docs/_data/site.cjs
Normal file
23
docs/_data/site.cjs
Normal file
@@ -0,0 +1,23 @@
|
||||
module.exports = async function () {
|
||||
return {
|
||||
dir: 'ltr',
|
||||
lang: 'en',
|
||||
name: 'Rocket',
|
||||
description: 'Rocket is the way to build fast static websites with a sprinkle of javascript',
|
||||
socialLinks: [
|
||||
{
|
||||
name: 'GitHub',
|
||||
url: 'https://github.com/modernweb-dev/rocket',
|
||||
},
|
||||
],
|
||||
gitSiteUrl: 'https://github.com/modernweb-dev/rocket',
|
||||
gitBranch: 'main',
|
||||
helpUrl: 'https://github.com/modernweb-dev/rocket/issues',
|
||||
logoAlt: 'Rocket Logo',
|
||||
iconColorMaskIcon: '#3f93ce',
|
||||
iconColorMsapplicationTileColor: '#1d3557',
|
||||
iconColorThemeColor: '#1d3557',
|
||||
socialMediaImage: '/_assets/social-media-image.jpg',
|
||||
// analytics: 'UA-131782693-2', // modern web key
|
||||
};
|
||||
};
|
||||
@@ -1,11 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = 'about/index.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
<meta name="menu:exclude" content="true" />
|
||||
|
||||
# About
|
||||
5
docs/about/slack.md
Normal file
5
docs/about/slack.md
Normal file
@@ -0,0 +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 join the Polymer slack by visiting https://www.polymer-project.org/slack-invite.
|
||||
@@ -1,13 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = 'about/slack.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Slack
|
||||
|
||||
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](https://www.polymer-project.org/slack-invite).
|
||||
9
docs/about/sponsor.md
Normal file
9
docs/about/sponsor.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Sponsor
|
||||
eleventyNavigation:
|
||||
key: Sponsor
|
||||
---
|
||||
|
||||
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).
|
||||
@@ -1,13 +0,0 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = 'about/sponsor.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Sponsor
|
||||
|
||||
We currently can only accept sponsoring in the form of services or contributions.
|
||||
|
||||
If you are interested in monetary sponsoring please [let us know](mailto:hello@modern-web.dev).
|
||||
14
docs/blog/index.md
Normal file
14
docs/blog/index.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Rocket Blog
|
||||
layout: blog
|
||||
eleventyNavigation:
|
||||
key: Blog
|
||||
order: 30
|
||||
pagination:
|
||||
data: collections.blog
|
||||
size: 10
|
||||
reverse: true
|
||||
alias: posts
|
||||
---
|
||||
|
||||
Discover articles from the core team and contributors about Rocket, tips and tricks included!
|
||||
12
docs/blog/introducing-check-html-links.11tydata.cjs
Normal file
12
docs/blog/introducing-check-html-links.11tydata.cjs
Normal file
@@ -0,0 +1,12 @@
|
||||
const { createSocialImage } = require('@rocket/cli');
|
||||
|
||||
module.exports = async function () {
|
||||
const socialMediaImage = await createSocialImage({
|
||||
title: 'Introducing',
|
||||
subTitle: 'check-html-links',
|
||||
footer: 'Rocket Blog',
|
||||
});
|
||||
return {
|
||||
socialMediaImage,
|
||||
};
|
||||
};
|
||||
@@ -1,16 +1,10 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '30--blog/introducing-check-html-links.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
|
||||
export const tags = ['html', 'javascript', 'webdev', 'node'];
|
||||
export const subTitle = 'A fast link checker for static HTML';
|
||||
// cover_image: https://dev-to-uploads.s3.amazonaws.com/i/an9z6f4hdll2jlne43u3.jpg
|
||||
```
|
||||
|
||||
# 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
|
||||
tags: [html, javascript, webdev, node]
|
||||
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/an9z6f4hdll2jlne43u3.jpg
|
||||
---
|
||||
|
||||
**TL;DR : I created a standalone tool that can help you fix all the broken links in your websites/documentation. You can check it out [on npm as check-html-links](https://www.npmjs.com/package/check-html-links)**
|
||||
|
||||
@@ -21,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 one 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 on 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 Node.js ecosystem
|
||||
- Preferably in the NodeJS ecosystem
|
||||
|
||||
## Focusing on Useful Output
|
||||
|
||||
@@ -87,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.
|
||||
|
||||
@@ -119,14 +113,14 @@ Results are gatherd on January 26, 2021:
|
||||
| web.dev | 830 | ~3.7s |
|
||||
| eslint.org | 3475 | ~12.4s |
|
||||
|
||||
## Being Part of the Node.js Ecosystem
|
||||
## Being part of the NodeJS 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 Node.js. 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 NodeJS. 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 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 👑.
|
||||
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 👑.
|
||||
|
||||
## Solution
|
||||
|
||||
@@ -136,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, srcset
|
||||
- use a Wasm parser (sax-wasm)
|
||||
- streams the HTML for performance
|
||||
- extracts every attribute value of id, href, src, srset
|
||||
- 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 checks your final HTML output so you need to execute it after your Static Site Generator.
|
||||
It does check your final html output so you need to execute it after your Static Site Generator.
|
||||
|
||||
```
|
||||
npx check-html-links _site
|
||||
```
|
||||
|
||||
## GitHub Action Usage
|
||||
## Usage Github 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).
|
||||
[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:
|
||||
|
||||
@@ -174,7 +168,7 @@ jobs:
|
||||
|
||||
## Comparison
|
||||
|
||||
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)
|
||||
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)
|
||||
|
||||
| Tool | Lines printed | Duration | Lang | Dependency Tree |
|
||||
| ---------------- | ------------- | -------- | ---- | --------------- |
|
||||
@@ -199,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).
|
||||
|
||||
---
|
||||
|
||||
9
docs/browserconfig.xml
Normal file
9
docs/browserconfig.xml
Normal file
@@ -0,0 +1,9 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<browserconfig>
|
||||
<msapplication>
|
||||
<tile>
|
||||
<square150x150logo src="/mstile-150x150.png"/>
|
||||
<TileColor>#1d3557</TileColor>
|
||||
</tile>
|
||||
</msapplication>
|
||||
</browserconfig>
|
||||
1
docs/docs/configuration/index.md
Normal file
1
docs/docs/configuration/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Configuration ||10
|
||||
88
docs/docs/configuration/overview.md
Normal file
88
docs/docs/configuration/overview.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Configuration >> Overview ||10
|
||||
|
||||
The configuration file is `rocket.config.js` or `rocket.config.mjs`.
|
||||
|
||||
The config files consists of the following parts:
|
||||
|
||||
```js
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
|
||||
export default {
|
||||
presets: [rocketLaunch()],
|
||||
emptyOutputDir: true,
|
||||
pathPrefix: 'subfolder-only-for-build',
|
||||
};
|
||||
```
|
||||
|
||||
Rocket is primarily build around plugins for each of it's 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)
|
||||
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)
|
||||
setupDevPlugins: [],
|
||||
|
||||
// add a plugin to the rollup build (e.g. optimization steps)
|
||||
setupBuildPlugins: [],
|
||||
|
||||
// add a plugin to eleventy (e.g. a filter packs)
|
||||
setupEleventyPlugins: [],
|
||||
|
||||
// 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")
|
||||
setupCliPlugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
## Adding Rollup Plugins
|
||||
|
||||
For some projects you might want to enable non-standard behaviors like importing JSON files as JavaScript.
|
||||
|
||||
```js
|
||||
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.
|
||||
|
||||
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';
|
||||
import { addPlugin } from 'plugins-manager';
|
||||
|
||||
/** @type {Partial<import("@rocket/cli").RocketCliOptions>} */
|
||||
const config = {
|
||||
setupDevAndBuildPlugins: [
|
||||
addPlugin({ name: 'json', plugin: json, location: 'top', options: { my: 'settings' } }),
|
||||
],
|
||||
};
|
||||
|
||||
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.
|
||||
|
||||
## Modifying Options of Plugins
|
||||
|
||||
All plugins which are either default or are added via a preset can still be adjusted by using `adjustPluginOptions`.
|
||||
|
||||
```js
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
/** @type {Partial<import("@rocket/cli").RocketCliOptions>} */
|
||||
const config = {
|
||||
setupDevAndBuildPlugins: [adjustPluginOptions('json', { my: 'overwrite settings' })],
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
41
docs/docs/configuration/setupEleventyComputedConfig.md
Normal file
41
docs/docs/configuration/setupEleventyComputedConfig.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# 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/).
|
||||
|
||||
Rocket exposes it via `setupEleventyComputedConfig`.
|
||||
|
||||
## 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)
|
||||
|
||||
👉 `rocket.config.mjs` (or your theme config file)
|
||||
|
||||
```js
|
||||
import { addPlugin } from 'plugins-manager';
|
||||
|
||||
/** @type {Partial<import("../../../types/main").RocketCliOptions>} */
|
||||
const config = {
|
||||
setupEleventyComputedConfig: [
|
||||
addPlugin({ name: 'greeting', plugin: data => `Welcome to the ${data.title} page.` }),
|
||||
],
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
|
||||
{% raw %}
|
||||
Now you can use everywhere {{ greeting }}.
|
||||
{% endraw %}
|
||||
And it will correctly replaced with a Welcome and the page title.
|
||||
|
||||
## Default Available Configs
|
||||
|
||||
```js
|
||||
[
|
||||
{ name: 'titleMeta', plugin: titleMetaPlugin },
|
||||
{ name: 'title', plugin: titlePlugin },
|
||||
{ name: 'eleventyNavigation', plugin: eleventyNavigationPlugin },
|
||||
{ name: 'section', plugin: sectionPlugin },
|
||||
{ name: 'socialMediaImage', plugin: socialMediaImagePlugin },
|
||||
];
|
||||
```
|
||||
1
docs/docs/eleventy-plugins/index.md
Normal file
1
docs/docs/eleventy-plugins/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Eleventy Plugins ||40
|
||||
94
docs/docs/eleventy-plugins/mdjs-unified.md
Normal file
94
docs/docs/eleventy-plugins/mdjs-unified.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Eleventy Plugins >> Markdown JavaScript (Mdjs)
|
||||
|
||||
Use mdjs in your 11ty site.
|
||||
|
||||
## Setup
|
||||
|
||||
```
|
||||
npm install @rocket/eleventy-plugin-mdjs
|
||||
```
|
||||
|
||||
Create an 11ty config file `.eleventy.js`
|
||||
|
||||
```js
|
||||
const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
|
||||
|
||||
module.exports = function (eleventyConfig) {
|
||||
eleventyConfig.addPlugin(pluginMdjs);
|
||||
};
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
We do use [plugins-manager](../tools/plugins-manager.md).
|
||||
|
||||
This example adds a CSS class to the `htmlHeading` plugin so heading links can be selected in CSS.
|
||||
|
||||
```js
|
||||
const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
|
||||
const { adjustPluginOptions } = require('plugins-manager');
|
||||
|
||||
module.exports = function (eleventyConfig) {
|
||||
eleventyConfig.addPlugin(pluginMdjs, {
|
||||
setupUnifiedPlugins: [
|
||||
adjustPluginOptions('htmlHeading', {
|
||||
properties: {
|
||||
className: ['anchor'],
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
Examples on how to insert a plugin right after creating the markdown AST.
|
||||
|
||||
```js
|
||||
const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
|
||||
const { addPlugin } = require('plugins-manager');
|
||||
const { myRemarkPlugin } = require('./my-remark-plugin.js');
|
||||
|
||||
module.exports = function (eleventyConfig) {
|
||||
eleventyConfig.addPlugin(pluginMdjs, {
|
||||
setupUnifiedPlugins: [
|
||||
addPlugin({ name: 'my-remark-plugin', plugin: myRemarkPlugin, location: 'markdown' }),
|
||||
],
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
Examples on how to insert a plugin right after creating the rehype AST.
|
||||
|
||||
```js
|
||||
const pluginMdjs = require('@rocket/eleventy-plugin-mdjs');
|
||||
const { addPlugin } = require('plugins-manager');
|
||||
const { myRehypePlugin } = require('./my-rehype-plugin.js');
|
||||
|
||||
module.exports = function (eleventyConfig) {
|
||||
eleventyConfig.addPlugin(pluginMdjs, {
|
||||
setupUnifiedPlugins: [
|
||||
addPlugin({ name: 'my-rehype-plugin', plugin: myRehypePlugin, location: 'remark2rehype' }),
|
||||
],
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
You can also add both
|
||||
|
||||
```js
|
||||
module.exports = function (eleventyConfig) {
|
||||
eleventyConfig.addPlugin(pluginMdjs, {
|
||||
setupUnifiedPlugins: [
|
||||
addPlugin({ name: 'my-remark-plugin', plugin: myRemarkPlugin, location: 'markdown' }),
|
||||
addPlugin({ name: 'my-rehype-plugin', plugin: myRehypePlugin, location: 'remark2rehype' }),
|
||||
],
|
||||
});
|
||||
};
|
||||
```
|
||||
12
docs/docs/index.md
Normal file
12
docs/docs/index.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Documentation
|
||||
eleventyNavigation:
|
||||
key: Docs
|
||||
order: 20
|
||||
---
|
||||
|
||||
Here you will find all the details for each of the packages/systems we offer.
|
||||
|
||||
You should check out:
|
||||
|
||||
- [@rocket/launch](./presets/launch.md) which is our default preset
|
||||
1
docs/docs/markdown-javascript/index.md
Normal file
1
docs/docs/markdown-javascript/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Markdown JavaScript ||30
|
||||
@@ -1,20 +1,6 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/30--markdown-javascript/10--overview.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
# Markdown JavaScript >> Overview || 10
|
||||
|
||||
# Overview
|
||||
|
||||
```js script
|
||||
import '@mdjs/mdjs-story/define';
|
||||
import '@mdjs/mdjs-preview/define';
|
||||
import { html } from '@mdjs/mdjs-story';
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
@@ -27,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
|
||||
@@ -66,18 +52,27 @@ customElements.define('my-el', MyEl);
|
||||
|
||||
## Demo Support (Story)
|
||||
|
||||
mdjs comes with some additional helpers you can choose to import:
|
||||
mdjs comes with some additional helpers you can choose to import via
|
||||
|
||||
````md
|
||||
```js script
|
||||
import '@mdjs/mdjs-story/define';
|
||||
import '@mdjs/mdjs-preview/define';
|
||||
import '@mdjs/mdjs-story/mdjs-story.js';
|
||||
import '@mdjs/mdjs-preview/mdjs-preview.js';
|
||||
```
|
||||
````
|
||||
|
||||
Once loaded you can use them like so:
|
||||
once loaded you can use them like so.
|
||||
|
||||
### Story
|
||||
````md
|
||||
```js script
|
||||
import '@mdjs/mdjs-story/mdjs-story.js';
|
||||
import '@mdjs/mdjs-preview/mdjs-preview.js';
|
||||
```
|
||||
````
|
||||
|
||||
once loaded you can use them like so.
|
||||
|
||||
### story
|
||||
|
||||
The code snippet will actually get executed at that place and you will have a live demo
|
||||
|
||||
@@ -93,7 +88,7 @@ export const JsStory = () => html` <demo-wc-card>JS Story</demo-wc-card> `;
|
||||
```
|
||||
````
|
||||
|
||||
#### Full Code Support
|
||||
#### full code support
|
||||
|
||||
````md
|
||||
```js story
|
||||
@@ -106,7 +101,7 @@ export const JsStory = () => {
|
||||
```
|
||||
````
|
||||
|
||||
### Preview Story
|
||||
### preview story
|
||||
|
||||
Will become a live demo wrapped in a container with a show code button.
|
||||
|
||||
@@ -124,6 +119,12 @@ export const JsPreviewStory = () => html` <demo-wc-card>JS Preview Story</demo-w
|
||||
|
||||
Here is a live example from [demo-wc-card](https://www.npmjs.com/package/demo-wc-card).
|
||||
|
||||
```js script
|
||||
import '@mdjs/mdjs-story/mdjs-story.js';
|
||||
import '@mdjs/mdjs-preview/mdjs-preview.js';
|
||||
import { html } from 'lit-html';
|
||||
```
|
||||
|
||||
```js preview-story
|
||||
import 'demo-wc-card/demo-wc-card.js';
|
||||
export const header = () => {
|
||||
@@ -131,79 +132,42 @@ export const header = () => {
|
||||
};
|
||||
```
|
||||
|
||||
```js story-code
|
||||
// not defined for android
|
||||
```
|
||||
|
||||
```js story-code
|
||||
// not defined for ios
|
||||
```
|
||||
|
||||
#### Story Code
|
||||
|
||||
If your preview is followed by a code blocks marked as `story-code` then those will be shown when switching between multiple platforms
|
||||
|
||||
````md
|
||||
```js preview-story
|
||||
// will be visible when platform web is selected
|
||||
export const JsPreviewStory = () => html` <demo-wc-card>JS Preview Story</demo-wc-card> `;
|
||||
```
|
||||
|
||||
```xml story-code
|
||||
<!-- will be visible when platform android is selected -->
|
||||
<Button
|
||||
android:id="@+id/demoWcCard"
|
||||
android:layout_width="wrap_content"
|
||||
android:layout_height="wrap_content"
|
||||
android:text="Android Code"
|
||||
style="@style/Widget.FooComponents.Demo.Wc.Card"
|
||||
/>
|
||||
```
|
||||
|
||||
```swift story-code
|
||||
// will be visible when platform ios is selected
|
||||
import DemoWc.Card
|
||||
|
||||
let card = DemoWcButton()
|
||||
```
|
||||
````
|
||||
|
||||
See it in action by opening up the code block and switching platforms
|
||||
|
||||
```js preview-story
|
||||
// will be visible when platform web is selected
|
||||
export const JsPreviewStory = () => html` <demo-wc-card>JS Preview Story</demo-wc-card> `;
|
||||
```
|
||||
|
||||
```xml story-code
|
||||
<!-- will be visible when platform android is selected -->
|
||||
<Button
|
||||
android:id="@+id/demoWcCard"
|
||||
android:layout_width="wrap_content"
|
||||
android:layout_height="wrap_content"
|
||||
android:text="Android Code"
|
||||
style="@style/Widget.FooComponents.Demo.Wc.Card"
|
||||
/>
|
||||
```
|
||||
|
||||
```swift story-code
|
||||
// will be visible when platform ios is selected
|
||||
import DemoWc.Card
|
||||
|
||||
let card = DemoWcButton()
|
||||
```
|
||||
|
||||
## Supported Systems
|
||||
|
||||
### es-dev-server
|
||||
|
||||
Preview your mdjs readme with live demos and auto reload.
|
||||
|
||||
- Add to your `package.json`:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"start": "es-dev-server",
|
||||
}
|
||||
```
|
||||
|
||||
- Create a `es-dev-server.config.js` in the root of your repo.
|
||||
|
||||
```js
|
||||
const { mdjsTransformer } = require('@mdjs/core');
|
||||
|
||||
module.exports = {
|
||||
nodeResolve: true,
|
||||
open: 'README.md',
|
||||
watch: true,
|
||||
responseTransformers: [mdjsTransformer],
|
||||
};
|
||||
```
|
||||
|
||||
### Storybook
|
||||
|
||||
Please check out [@open-wc/demoing-storybook](https://open-wc.org/demoing/) for a fully integrated setup.
|
||||
|
||||
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 pages, Markdown files, issues, pull requests...
|
||||
See live demos directly inside github page, markdown files, issues, pull requests...
|
||||
|
||||
Please check out [mdjs-viewer](https://github.com/open-wc/mdjs-viewer).
|
||||
|
||||
@@ -215,7 +179,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');
|
||||
@@ -233,7 +197,7 @@ const page = await mdjsDocPage(markdownString);
|
||||
|
||||
#### `mdjsProcess`
|
||||
|
||||
Pass in multiple Markdown documents and you get back all the JavaScript code and rendered HTML.
|
||||
Pass in multiple markdown documents and you get back all the jsCode and rendered html.
|
||||
|
||||
```js
|
||||
const { mdjsProcess } = require('@mdjs/core');
|
||||
19
docs/docs/markdown-javascript/preview.md
Normal file
19
docs/docs/markdown-javascript/preview.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Markdown JavaScript >> Preview ||20
|
||||
|
||||
You can showcase live running code by annotating a code block with `js preview-story`.
|
||||
|
||||
````md
|
||||
```js preview-story
|
||||
import { html } from 'lit-html';
|
||||
|
||||
export const foo = () => html` <p>my html</p> `;
|
||||
```
|
||||
````
|
||||
|
||||
will result in
|
||||
|
||||
```js preview-story
|
||||
import { html } from 'lit-html';
|
||||
|
||||
export const foo = () => html` <p>my html</p> `;
|
||||
```
|
||||
19
docs/docs/markdown-javascript/story.md
Normal file
19
docs/docs/markdown-javascript/story.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Markdown JavaScript >> Story ||30
|
||||
|
||||
You can showcase live running code by annotating a code block with `js story`.
|
||||
|
||||
````md
|
||||
```js story
|
||||
import { html } from 'lit-html';
|
||||
|
||||
export const foo = () => html` <p>my html</p> `;
|
||||
```
|
||||
````
|
||||
|
||||
will result in
|
||||
|
||||
```js story
|
||||
import { html } from 'lit-html';
|
||||
|
||||
export const foo = () => html` <p>my html</p> `;
|
||||
```
|
||||
21
docs/docs/presets/blog.md
Normal file
21
docs/docs/presets/blog.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# Presets >> Blog ||30
|
||||
|
||||
Enable writing blog posts within your rocket site
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm i @rocket/blog
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
👉 `rocket.config.mjs`
|
||||
|
||||
```js
|
||||
import { rocketBlog } from '@rocket/blog';
|
||||
|
||||
export default {
|
||||
presets: [rocketBlog()],
|
||||
};
|
||||
```
|
||||
5
docs/docs/presets/index.md
Normal file
5
docs/docs/presets/index.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
excludeFromSearch: true
|
||||
---
|
||||
|
||||
# Presets ||20
|
||||
119
docs/docs/presets/launch.md
Normal file
119
docs/docs/presets/launch.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 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.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm i @rocket/launch
|
||||
```
|
||||
|
||||
👉 `rocket.config.mjs`
|
||||
|
||||
```js
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
|
||||
export default {
|
||||
presets: [rocketLaunch()],
|
||||
};
|
||||
```
|
||||
|
||||
## Data
|
||||
|
||||
Most data comes from `site.cjs`.
|
||||
|
||||
There is also a specific `rocketLaunch.json`.
|
||||
|
||||
The footer data comes from `footer.json`
|
||||
|
||||
## Inline Notification
|
||||
|
||||
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.
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
|
||||
First you need to import the script
|
||||
|
||||
````
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
````
|
||||
|
||||
### Tip
|
||||
|
||||
<inline-notification type="tip">
|
||||
|
||||
I am a tip
|
||||
|
||||
</inline-notification>
|
||||
|
||||
**Usage**
|
||||
|
||||
```md
|
||||
<inline-notification type="tip">
|
||||
|
||||
I am a tip
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
|
||||
### Modify the title
|
||||
|
||||
To override the title you can provide a property success.
|
||||
|
||||
<inline-notification type="tip" title="success">
|
||||
|
||||
I am a success message
|
||||
|
||||
</inline-notification>
|
||||
|
||||
**Usage**
|
||||
|
||||
```md
|
||||
<inline-notification type="tip" title="success">
|
||||
|
||||
I am a success message
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
|
||||
### Warning
|
||||
|
||||
<inline-notification type="warning">
|
||||
|
||||
I am a warning
|
||||
|
||||
</inline-notification>
|
||||
|
||||
**Usage**
|
||||
|
||||
```md
|
||||
<inline-notification type="warning">
|
||||
|
||||
I am a warning
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
|
||||
### Danger
|
||||
|
||||
<inline-notification type="danger">
|
||||
|
||||
I am a dangerous message
|
||||
|
||||
</inline-notification>
|
||||
|
||||
**Usage**
|
||||
|
||||
```md
|
||||
<inline-notification type="danger">
|
||||
|
||||
I am a dangerous message
|
||||
|
||||
</inline-notification>
|
||||
```
|
||||
19
docs/docs/presets/search.md
Normal file
19
docs/docs/presets/search.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Presets >> Search ||20
|
||||
|
||||
Add a search for all your static content.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm i @rocket/search
|
||||
```
|
||||
|
||||
👉 `rocket.config.mjs`
|
||||
|
||||
```js
|
||||
import { rocketSearch } from '@rocket/search';
|
||||
|
||||
export default {
|
||||
presets: [rocketSearch()],
|
||||
};
|
||||
```
|
||||
38
docs/docs/tools/check-html-links.md
Normal file
38
docs/docs/tools/check-html-links.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# Tools >> Check Html Links ||30
|
||||
|
||||
A fast checker for broken links/references in html.
|
||||
|
||||
## Features
|
||||
|
||||
- Checks all html files for broken local links/references (in href, src, srcset)
|
||||
- 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
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
npm i -D check-html-links
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
npx check-html-links _site
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
|
||||
|
||||
## Comparision
|
||||
|
||||
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)
|
||||
|
||||
| Tool | Lines printed | Times | Lang | Dependency Tree |
|
||||
| ---------------- | ------------- | ------ | ---- | --------------- |
|
||||
| check-html-links | 38 | ~2.5s | node | 19 |
|
||||
| link-checker | 3000+ | ~11s | node | 106 |
|
||||
| hyperlink | 68 | 4m 20s | node | 481 |
|
||||
| htmltest | 1000+ | ~0.7s | GO | - |
|
||||
|
Before Width: | Height: | Size: 214 KiB After Width: | Height: | Size: 214 KiB |
1
docs/docs/tools/index.md
Normal file
1
docs/docs/tools/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Tools ||50
|
||||
269
docs/docs/tools/plugins-manager.md
Normal file
269
docs/docs/tools/plugins-manager.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# Tools >> Plugins Manager ||10
|
||||
|
||||
The Plugins Manager replaces the specific registration/execution (with options) in a given plugin system by an intend to use a plugin (with these options).
|
||||
This allows your users to adjust the options before actually applying the plugins.
|
||||
|
||||
## Problem
|
||||
|
||||
Many plugin systems require you to either execute a plugin function like in `rollup`.
|
||||
|
||||
```js
|
||||
import json from '@rollup/plugin-json';
|
||||
export default {
|
||||
plugins: [json({ preferConst: true })],
|
||||
};
|
||||
```
|
||||
|
||||
or add it in a special way like in `eleventy`
|
||||
|
||||
```js
|
||||
const pluginSyntaxHighlight = require('@11ty/eleventy-plugin-syntaxhighlight');
|
||||
module.exports = function (eleventyConfig) {
|
||||
eleventyConfig.addPlugin(pluginSyntaxHighlight, { templateFormats: ['md'] });
|
||||
};
|
||||
```
|
||||
|
||||
or `unified/remark`.
|
||||
|
||||
```js
|
||||
var unified = require('unified');
|
||||
var markdown = require('remark-parse');
|
||||
var toc = require('remark-toc');
|
||||
|
||||
var processor = unified().use(markdown).use(toc, { maxDepth: 2 });
|
||||
// ...
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
This means if you wish to define default plugins and allow your user to override all of the settings it's "impossible".
|
||||
|
||||
## Solution
|
||||
|
||||
The plugins manager let's you orchestrate a set of "meta plugins" which are defined by
|
||||
|
||||
- name
|
||||
- plugin
|
||||
- options
|
||||
|
||||
```js
|
||||
import beep from '@rollup/plugin-beep';
|
||||
import url from '@rollup/plugin-url';
|
||||
|
||||
let metaPlugins = [
|
||||
{ name: 'beep', plugin: beep },
|
||||
{ name: 'url', plugin: url, options: { limit: 10000 } },
|
||||
];
|
||||
```
|
||||
|
||||
This array can be modified by adding/removing or adjusting options.
|
||||
|
||||
```js
|
||||
// raw add
|
||||
metaPlugins.push({
|
||||
// another plugin
|
||||
});
|
||||
|
||||
// raw adjust
|
||||
metaPlugins[1].options.limit = 20000;
|
||||
```
|
||||
|
||||
And then you can convert it into the specific format that can be assigned to your system in question.
|
||||
|
||||
```js
|
||||
// execute plugins for rollup
|
||||
const plugins = metaPlugins.map(pluginObj => {
|
||||
if (pluginObj.options) {
|
||||
return pluginObj.plugin(pluginObj.options);
|
||||
} else {
|
||||
return pluginObj.plugin();
|
||||
}
|
||||
});
|
||||
|
||||
// rollup.config.js
|
||||
export default {
|
||||
plugins,
|
||||
};
|
||||
```
|
||||
|
||||
### Adding Helpers
|
||||
|
||||
Doing array manipulations is kinda error-prone so we offer encourage to use an array of setup function. Where as each setup function can either add a new plugin (with a unique name) or adjust an already existing plugin.
|
||||
|
||||
```js
|
||||
import { addPlugin, adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
const systemSetupFunctions = [
|
||||
addPlugin({ name: 'first', plugin: first }),
|
||||
addPlugin({ name: 'second', plugin: second }),
|
||||
];
|
||||
const userSetupFunctions = [adjustPluginOptions('first', { my: 'options' })];
|
||||
```
|
||||
|
||||
Arrays of functions can by merged like so
|
||||
|
||||
```js
|
||||
const finalSetupFunctions = [...systemSetupFunctions, ...userSetupFunctions];
|
||||
```
|
||||
|
||||
and then converted to the final output.
|
||||
|
||||
```js
|
||||
import { metaPluginsToRollupPlugins } from 'plugins-manager';
|
||||
|
||||
const plugins = metaPluginsToRollupPlugins(finalSetupFunctions, metaPlugins);
|
||||
```
|
||||
|
||||
## Adding a Plugin
|
||||
|
||||
This makes sure that
|
||||
|
||||
- the name is unique
|
||||
- you can add at at `top`, `bottom` and `after/before` a given other plugin
|
||||
|
||||
By default it adds at the bottom.
|
||||
|
||||
```js
|
||||
import json from '@rollup/plugin-json';
|
||||
import { addPlugin } from 'plugins-manager';
|
||||
|
||||
const userSetupFunctions = [
|
||||
addPlugin({ name: 'json', plugin: json, options: { preferConst: true } }),
|
||||
];
|
||||
```
|
||||
|
||||
Example usage:
|
||||
|
||||
```js
|
||||
addPlugin({ name: 'json', plugin: json }); // Add at the bottom (default)
|
||||
addPlugin({ name: 'json', plugin: json, location: 'top' }); // Add at the top/beginning of the array
|
||||
addPlugin({ name: 'json', plugin: json, location: 'beep' }); // Add after (default) plugin 'beep'
|
||||
addPlugin({ name: 'json', plugin: json, location: 'beep', how: 'before' }); // Add before plugin 'beep'
|
||||
```
|
||||
|
||||
## Adjusting Plugin Options
|
||||
|
||||
Adjusting options means to either
|
||||
|
||||
- flatly merge objects (e.g. only the first level will be preserved)
|
||||
- calling a function to do the merge yourself
|
||||
- setting the raw value (if not an object or function)
|
||||
|
||||
```js
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
const userSetupFunctions = [
|
||||
adjustPluginOptions('json', { preferConst: false, anotherOption: 'format' }),
|
||||
];
|
||||
```
|
||||
|
||||
Example usage:
|
||||
|
||||
```js
|
||||
// given
|
||||
addPlugin({
|
||||
name: 'json',
|
||||
plugin: json,
|
||||
options: {
|
||||
other: {
|
||||
nested: 'other.nested',
|
||||
nested2: 'other.nested2',
|
||||
},
|
||||
main: true,
|
||||
},
|
||||
});
|
||||
|
||||
// merge objects flately
|
||||
adjustPluginOptions('json', { other: { nested: '--overwritten--' } });
|
||||
// resulting options = { other: { nested: '--overwritten--' }, main: true }
|
||||
// NOTE: nested2 is removed
|
||||
|
||||
// merge via function
|
||||
adjustPluginOptions('json', config => ({ other: { ...config.other, nested: '--overwritten--' } }));
|
||||
// resulting options = { other: { nested: '--overwritten--', nested2: 'other.nested2' }, main: true }
|
||||
|
||||
// merge via function to override full options
|
||||
adjustPluginOptions('json', config => ({ only: 'this' }));
|
||||
// resulting options = { only: 'this' }
|
||||
|
||||
// setting a raw value
|
||||
adjustPluginOptions('json', false);
|
||||
// resulting options = false
|
||||
```
|
||||
|
||||
## Converting metaPlugins to an actual plugin
|
||||
|
||||
To execute all setup function you can use this little helper
|
||||
|
||||
```js
|
||||
const finalMetaPlugins = executeSetupFunctions(finalSetupFunctions, metaPlugins);
|
||||
```
|
||||
|
||||
And then you can convert it into your format.
|
||||
For Rollup you would execute the plugin with the options if there are any.
|
||||
|
||||
```js
|
||||
const plugins = finalMetaPlugins.map(pluginObj => {
|
||||
if (pluginObj.options) {
|
||||
return pluginObj.plugin(pluginObj.options);
|
||||
} else {
|
||||
return pluginObj.plugin();
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
Rollup has a more specific helper that handles
|
||||
|
||||
- `config.setupPlugins`
|
||||
|
||||
Note: if you provide `config.plugins` then it will return that directly ignoring `setupPlugins`
|
||||
|
||||
```js
|
||||
import { metaConfigToRollupConfig } from 'plugins-manager';
|
||||
|
||||
const finalConfig = metaConfigToRollupConfig(currentConfig, defaultMetaPlugins);
|
||||
```
|
||||
|
||||
Web Dev Server has a more specific helper that handles
|
||||
|
||||
- `config.setupPlugins`
|
||||
- `config.setupRollupPlugins`
|
||||
|
||||
Note: if you provide `config.plugins` then it will return that directly ignoring `setupPlugins` and `setupRollupPlugins`
|
||||
|
||||
```js
|
||||
import { metaConfigToWebDevServerConfig } from 'plugins-manager';
|
||||
import { fromRollup } from '@web/dev-server-rollup';
|
||||
|
||||
const finalConfig = metaConfigToWebDevServerConfig(currentConfig, defaultMetaPlugins, {
|
||||
rollupWrapperFunction: fromRollup,
|
||||
});
|
||||
```
|
||||
|
||||
Eleventy
|
||||
|
||||
```js
|
||||
module.exports = eleventyConfig => {
|
||||
for (const pluginObj of metaPlugins) {
|
||||
if (pluginObj.options) {
|
||||
eleventyConfig.addPlugin(pluginObj.plugin, pluginObj.options);
|
||||
} else {
|
||||
eleventyConfig.addPlugin(pluginObj.plugin);
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
Unified/Remark
|
||||
|
||||
```js
|
||||
const parser = unified();
|
||||
|
||||
for (const pluginObj of metaPlugins) {
|
||||
parser.use(pluginObj.plugin, pluginObj.options);
|
||||
}
|
||||
```
|
||||
@@ -1,22 +1,15 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '20--docs/50--tools/20--rollup-config.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Rollup Config
|
||||
# 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 JavaScript as input and/or output
|
||||
- Set HTML or JS as input and/or output
|
||||
- Optimized for browsers which support modules
|
||||
- Loads polyfills using feature detection
|
||||
- Minifies JavaScript
|
||||
- Generates a service worker
|
||||
- Minifies JS
|
||||
- Minifies lit-html templates
|
||||
|
||||
## Setup
|
||||
@@ -32,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',
|
||||
@@ -61,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.
|
||||
|
||||
@@ -73,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:
|
||||
|
||||
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 15 KiB |
|
Before Width: | Height: | Size: 3.7 KiB After Width: | Height: | Size: 3.7 KiB |
@@ -1,12 +1,4 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/30--configuration/10--getting-started.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Getting Started
|
||||
# Configuration >> Getting Started ||10
|
||||
|
||||
The main config file is `rocket.config.js` or `rocket.config.mjs`.
|
||||
|
||||
@@ -24,23 +16,23 @@ export default /** @type {Partial<import('@rocket/cli').RocketCliOptions>} */ ({
|
||||
});
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Adding Remark/Unified Plugins
|
||||
|
||||
If you want to add a plugin to the Markdown processing you can use `setupUnifiedPlugins`.
|
||||
If you want to a plugin to the markdown processing you can use `setupUnifiedPlugins`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```js
|
||||
import emoji from 'remark-emoji';
|
||||
import { addPlugin } from 'plugins-manager';
|
||||
|
||||
/** @type {Partial<import('@rocket/cli').RocketCliOptions>} */
|
||||
export default ({
|
||||
const config = {
|
||||
setupUnifiedPlugins: [addPlugin({ location: 'markdown', name: 'emoji', plugin: emoji })],
|
||||
});
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
};
|
||||
|
||||
For plugins that should handle the Markdown <abbr title="Abstract Syntax Tree">AST</abbr> you should use `addPlugin({ location: 'markdown', name: 'my-plugin', plugin: MyPlugin})`. <br>
|
||||
While for the rehype AST you should use `addPlugin({ location: 'remark2rehype', name: 'my-plugin', plugin: MyPlugin})`.
|
||||
export default config;
|
||||
```
|
||||
|
||||
For plugins that should handle the markdown <abbr title="Abstract Syntax Tree">AST</abbr> you should use `addPlugin({ location: 'markdown', name: 'my-plugin', plugin: MyPlugin})`. <br>
|
||||
While for the rehype ast you should use `addPlugin({ location: 'remark2rehype', name: 'my-plugin', plugin: MyPlugin})`.
|
||||
1
docs/guides/configuration/index.md
Normal file
1
docs/guides/configuration/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Configuration ||30
|
||||
@@ -1,12 +1,4 @@
|
||||
```js server
|
||||
/* START - Rocket auto generated - do not touch */
|
||||
export const sourceRelativeFilePath = '10--guides/10--first-pages/20--adding-pages.rocket.md';
|
||||
import { pageTree, setupUnifiedPlugins, footerMenu, layout } from '../../recursive.data.js';
|
||||
export { pageTree, setupUnifiedPlugins, footerMenu, layout };
|
||||
/* END - Rocket auto generated - do not touch */
|
||||
```
|
||||
|
||||
# Adding Pages
|
||||
# First Pages >> Adding Pages ||12
|
||||
|
||||
<inline-notification type="warning">
|
||||
|
||||
@@ -16,17 +8,17 @@ It can help to examine each new page and menu carefully, to come to terms with t
|
||||
|
||||
</inline-notification>
|
||||
|
||||
## 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 its own sidebar navigation.
|
||||
In most cases you will have multiple sections in your website and each of those sections will come with it's own sidebar navigation.
|
||||
|
||||
To create a section you need to create a folder with an `index.rocket.md`.
|
||||
To create a section you need to create a folder with an `index.md`.
|
||||
|
||||
```bash
|
||||
mkdir docs/guides
|
||||
```
|
||||
|
||||
👉 `docs/guides/index.rocket.md`
|
||||
👉 `docs/guides/index.md`
|
||||
|
||||
```md
|
||||
# Guides
|
||||
@@ -46,40 +38,40 @@ 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.
|
||||
|
||||
To create a category you need to create a folder with an `index.rocket.md`.
|
||||
To create a category you need to create a folder with an `index.md`.
|
||||
|
||||
```bash
|
||||
mkdir docs/guides/first-pages/
|
||||
```
|
||||
|
||||
👉 `docs/guides/first-pages/index.rocket.md`
|
||||
👉 `docs/guides/first-pages/index.md`
|
||||
|
||||
```md
|
||||
# First Pages
|
||||
```
|
||||
|
||||
## Adding a Page to a Category
|
||||
## Adding a page to a category
|
||||
|
||||
👉 `docs/guides/first-pages/getting-started.rocket.md`
|
||||
👉 `docs/guides/first-pages/getting-started.md`
|
||||
|
||||
```md
|
||||
# Getting Started
|
||||
# First Pages >> Getting Started
|
||||
|
||||
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 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.
|
||||
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.
|
||||
|
||||
```md
|
||||
## Headings as Anchor and Menu Items
|
||||
## Headings as anchor and menu items
|
||||
|
||||
_**Within**_ any page, you can still add links to your navigation!
|
||||
```
|
||||
@@ -88,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.
|
||||
117
docs/guides/first-pages/getting-started.md
Normal file
117
docs/guides/first-pages/getting-started.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# First Pages >> Getting Started ||10
|
||||
|
||||
Rocket is has the following prerequisits:
|
||||
|
||||
- [Node 14+](https://nodejs.org/en/)
|
||||
|
||||
Make sure they are installed before proceeding.
|
||||
|
||||
## Setup
|
||||
|
||||
The fastest way to get started is by using an existing preset like the launch preset.
|
||||
|
||||
1. Start with an empty new folder
|
||||
|
||||
```
|
||||
mkdir my-project
|
||||
cd my-project
|
||||
npm init -y
|
||||
```
|
||||
|
||||
2. Install dependencies
|
||||
|
||||
```
|
||||
npm install --save-dev @rocket/cli @rocket/launch
|
||||
```
|
||||
|
||||
3. Add to your .gitignore
|
||||
|
||||
```
|
||||
## Rocket ignore files (need to be the full relative path to the folders)
|
||||
docs/_merged_data/
|
||||
docs/_merged_assets/
|
||||
docs/_merged_includes/
|
||||
```
|
||||
|
||||
<inline-notification type="danger">
|
||||
|
||||
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!
|
||||
|
||||
</inline-notification>
|
||||
|
||||
4. Create a `rocket.config.mjs` (or `.js` if you have type: "module" in you package.json)
|
||||
|
||||
```js
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
|
||||
export default {
|
||||
presets: [rocketLaunch()],
|
||||
};
|
||||
```
|
||||
|
||||
5. (optionally) Create a file `.eleventyignore` (this file will be needed once you start customizing presets)
|
||||
|
||||
```
|
||||
node_modules/**
|
||||
/docs/_assets
|
||||
/docs/_includes
|
||||
/docs/_data
|
||||
```
|
||||
|
||||
<inline-notification type="warning" title="note">
|
||||
|
||||
All further pathes are relative to your project root (my-project in this case)
|
||||
|
||||
</inline-notification>
|
||||
|
||||
## Add your first page
|
||||
|
||||
👉 `docs/index.md`
|
||||
|
||||
```md
|
||||
# Welcome to your Rocket site
|
||||
|
||||
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:
|
||||
|
||||
👉 `package.json`
|
||||
|
||||
Add `"start": "rocket start"` to your package.json
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"start": "rocket start"
|
||||
}
|
||||
```
|
||||
|
||||
Now you can launch your site locally with
|
||||
|
||||
```bash
|
||||
npm run start
|
||||
```
|
||||
|
||||
## Taking Inventory Before Adding Pages:
|
||||
|
||||
We're about to add both content and navigation at the same time.
|
||||
|
||||
It can be helpful to take an inventory, before we start, to separate basic setup from the creation of content and navigation.
|
||||
|
||||
- We built the project with basic npm commands
|
||||
- Added a couple required files manually
|
||||
- Adjusted package.json
|
||||
- **doc/index.md** to seed the content
|
||||
- Launches with `npm start`
|
||||
|
||||
That's all it takes to get a new super-fast and powerful site, complete with a service worker, default styling, navigation, and ready to deploy as a plain old static files.
|
||||
|
||||
```js script
|
||||
import '@rocket/launch/inline-notification/inline-notification.js';
|
||||
```
|
||||
1
docs/guides/first-pages/index.md
Normal file
1
docs/guides/first-pages/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# First Pages ||10
|
||||
7
docs/guides/first-pages/link-to-other-pages.md
Normal file
7
docs/guides/first-pages/link-to-other-pages.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# First Pages >> Linking ||20
|
||||
|
||||
Standard markdown applies and you can link via
|
||||
|
||||
```md
|
||||
[visible label](./path/to/other-file.md)
|
||||
```
|
||||
49
docs/guides/first-pages/manage-sidebar.md
Normal file
49
docs/guides/first-pages/manage-sidebar.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# First Pages >> Managing sidebar ||30
|
||||
|
||||
The sidebar will show all the content of the current section.
|
||||
|
||||
## Nesting Pages
|
||||
|
||||
You nest by adding `>>` between parent and child.
|
||||
|
||||
## Sorting Pages
|
||||
|
||||
You can sort by adding `||xx` at the end.
|
||||
|
||||
e.g.
|
||||
|
||||
```
|
||||
# Second || 20
|
||||
# First || 10
|
||||
```
|
||||
|
||||
Will be ordered as `First`, `Second`,
|
||||
|
||||
## How it works
|
||||
|
||||
Internally `# Foo >> Bar >> Baz ||20` get's converted to.
|
||||
|
||||
```
|
||||
---
|
||||
title: Bar: Baz
|
||||
eleventyNavigation:
|
||||
key: Foo >> Bar >> Baz
|
||||
parent: Foo >> Bar
|
||||
order: 20
|
||||
---
|
||||
```
|
||||
|
||||
You can also look at this live playground:
|
||||
|
||||
```js story
|
||||
import { html } from 'lit-html';
|
||||
|
||||
export const headlineConverter = () => html`
|
||||
<p>
|
||||
<strong style="color: red;">TODO: </strong>I will become a web component that has an input and
|
||||
out that live udpates
|
||||
</p>
|
||||
`;
|
||||
```
|
||||
|
||||
How it then works is very similar to https://www.11ty.dev/docs/plugins/navigation/
|
||||
5
docs/guides/first-pages/urls.md
Normal file
5
docs/guides/first-pages/urls.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# First Pages >> Urls ||100
|
||||
|
||||
Urls will be represented by the folder structure...
|
||||
|
||||
You can use a frontmatter with permalink to override
|
||||
25
docs/guides/first-pages/use-javascript.md
Normal file
25
docs/guides/first-pages/use-javascript.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# First Pages >> Use JavaScript ||40
|
||||
|
||||
You can use `js script` to execute javascript (type = module)
|
||||
|
||||
````
|
||||
```js script
|
||||
console.log('foo');
|
||||
```
|
||||
````
|
||||
|
||||
This can be useful for importing web components and using them in markdown
|
||||
|
||||
````
|
||||
```js script
|
||||
import 'magic-reveal/magic-reveal.js';
|
||||
|
||||
<magic-reveal>
|
||||
|
||||
This text will get magically revealed. I can **still** use markdown as long as between the opening/closing tag there is an empty line.
|
||||
|
||||
</magic-reveal>
|
||||
```
|
||||
````
|
||||
|
||||
or you can use `js story`, `js preview-story`, ...
|
||||
1
docs/guides/go-live/index.md
Normal file
1
docs/guides/go-live/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Go Live ||40
|
||||
51
docs/guides/go-live/overview.md
Normal file
51
docs/guides/go-live/overview.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Go Live >> Overview ||10
|
||||
|
||||
A few things are usually needed before going live "for real".
|
||||
|
||||
## Add a not found page
|
||||
|
||||
When a user enters a url that does not exists then a "famous" 404 page not found error occures.
|
||||
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.
|
||||
|
||||
To enable it you need to creating a 404.md and use the 404 layout.
|
||||
|
||||
👉 `docs/404.md`
|
||||
|
||||
```
|
||||
---
|
||||
layout: 404.njk
|
||||
permalink: 404.html
|
||||
---
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
👉 `docs/sitemap.njk`
|
||||
|
||||
{% raw %}
|
||||
|
||||
```
|
||||
---
|
||||
layout: pure-content.njk
|
||||
permalink: /sitemap.xml
|
||||
eleventyExcludeFromCollections: true
|
||||
---
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
{% for page in collections.all %}
|
||||
<url>
|
||||
<loc>{{ rocketConfig.absoluteBaseUrl }}{{ page.url | url }}</loc>
|
||||
<lastmod>{{ page.date.toISOString() }}</lastmod>
|
||||
<changefreq>{{ page.data.changeFreq if page.data.changeFreq else "monthly" }}</changefreq>
|
||||
</url>
|
||||
{% endfor %}
|
||||
</urlset>
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
131
docs/guides/go-live/social-media.md
Normal file
131
docs/guides/go-live/social-media.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# Go Live >> Social Media ||20
|
||||
|
||||
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
|
||||
|
||||
<img src="{{ socialMediaImage }}" width="1200" height="630" alt="Social Media Image of this page" style="border: 1px solid #000" />
|
||||
|
||||
There are multiple ways you can modify it.
|
||||
|
||||
Note: If your logo has an `<?xml>` 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
|
||||
|
||||
You can create your own image and link it with something like this
|
||||
|
||||
```
|
||||
---
|
||||
socialMediaImage: path/to/my/image.png
|
||||
---
|
||||
```
|
||||
|
||||
## Providing your own text
|
||||
|
||||
Sometimes extracting the title + title of parent is not enough but you still want to use the "default image".
|
||||
|
||||
You can create an `11tydata.cjs` file next to your page. If your page is `docs/guides/overview.md` then you create a `docs/guides/overview.11tydata.cjs`.
|
||||
|
||||
In there you can use the default `createSocialImage` but provide your own values.
|
||||
|
||||
```js
|
||||
const { createSocialImage } = require('@rocket/cli');
|
||||
|
||||
module.exports = async function () {
|
||||
const socialMediaImage = await createSocialImage({
|
||||
title: 'Learning Rocket',
|
||||
subTitle: 'Have a website',
|
||||
subTitle2: 'in 5 Minutes',
|
||||
footer: 'Rocket Guides',
|
||||
// you can also override the svg only for this page by providing
|
||||
// createSocialImageSvg: async () => '<svg>...</svg>'
|
||||
});
|
||||
return {
|
||||
socialMediaImage,
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
👉 `rocket.config.mjs`
|
||||
|
||||
```js
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
/** @type {Partial<import("@rocket/cli").RocketCliOptions>} */
|
||||
const config = {
|
||||
setupEleventyComputedConfig: [
|
||||
adjustPluginOptions('socialMediaImage', {
|
||||
createSocialImageSvg: async ({
|
||||
title = '',
|
||||
subTitle = '',
|
||||
subTitle2 = '',
|
||||
footer = '',
|
||||
logo = '',
|
||||
}) => {
|
||||
let svgStr = `
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630" style="fill: #ecedef;">
|
||||
<defs/>
|
||||
<rect width="100%" height="100%" fill="#38393e"/>
|
||||
<g transform="matrix(0.45, 0, 0, 0.45, 300, 60)">${logo}</g>
|
||||
<g style="
|
||||
font-size: 70px;
|
||||
text-anchor: middle;
|
||||
font-family: 'Bitstream Vera Sans','Helvetica',sans-serif;
|
||||
font-weight: 700;
|
||||
">
|
||||
<text x="50%" y="470">
|
||||
${title}
|
||||
</text>
|
||||
<text x="50%" y="520" style="font-size: 30px;">
|
||||
${subTitle}
|
||||
</text>
|
||||
</g>
|
||||
<text x="10" y="620" style="font-size: 30px; fill: gray;">
|
||||
${footer}
|
||||
</text>
|
||||
</svg>
|
||||
`;
|
||||
return svgStr;
|
||||
},
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
WARNING: Untested example
|
||||
|
||||
👉 `rocket.config.mjs`
|
||||
|
||||
{% raw %}
|
||||
|
||||
```js
|
||||
import { adjustPluginOptions } from 'plugins-manager';
|
||||
|
||||
/** @type {Partial<import("@rocket/cli").RocketCliOptions>} */
|
||||
const config = {
|
||||
setupEleventyComputedConfig: [
|
||||
adjustPluginOptions('socialMediaImage', {
|
||||
createSocialImageSvg: async (args = {}) => {
|
||||
// inside of the svg you can use {{ title }}
|
||||
const svgBuffer = await fs.promises.readFile('/path/to/your/svg/file');
|
||||
const svg = logoBuffer.toString();
|
||||
return nunjucks.renderString(svg, args);
|
||||
},
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
{% endraw %}
|
||||
```
|
||||
13
docs/guides/index.11tydata.cjs
Normal file
13
docs/guides/index.11tydata.cjs
Normal file
@@ -0,0 +1,13 @@
|
||||
const { createSocialImage } = require('@rocket/cli');
|
||||
|
||||
module.exports = async function () {
|
||||
const socialMediaImage = await createSocialImage({
|
||||
title: 'Learning Rocket',
|
||||
subTitle: 'Have a website',
|
||||
subTitle2: 'in 5 Minutes',
|
||||
footer: 'Rocket Guides',
|
||||
});
|
||||
return {
|
||||
socialMediaImage,
|
||||
};
|
||||
};
|
||||
8
docs/guides/index.md
Normal file
8
docs/guides/index.md
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Learning Rocket
|
||||
eleventyNavigation:
|
||||
key: Guides
|
||||
order: 10
|
||||
---
|
||||
|
||||
Rocket is a fundamentally straight forward way to generate static pages while still allowing to sprinkle in some JavaScript where needed.
|
||||
106
docs/guides/presets/create-your-own.md
Normal file
106
docs/guides/presets/create-your-own.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Presets >> Create your own || 90
|
||||
|
||||
A preset is 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`.
|
||||
|
||||
You then create the setup function for it with only one property called `path` which will allow Rocket to properly resolve it.
|
||||
|
||||
## Create a Preset Config File
|
||||
|
||||
👉 `fire-theme/fireTheme.js`
|
||||
|
||||
```js
|
||||
import path from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
export function fireTheme() {
|
||||
return {
|
||||
path: path.resolve(__dirname),
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Once you have that you can start filling in content you need.
|
||||
|
||||
For example a we could override the full `layout.css` by adding a it like so
|
||||
|
||||
👉 `fire-theme/layout.css`
|
||||
|
||||
```css
|
||||
body {
|
||||
background: hotpink;
|
||||
}
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
👉 `rocket-config.js`
|
||||
|
||||
```js
|
||||
import { rocketLaunch } from '@rocket/launch';
|
||||
import { fireTheme } from 'path/to/fire-theme/fireTheme.js';
|
||||
|
||||
export default {
|
||||
presets: [rocketLaunch(), fireTheme()],
|
||||
};
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
1. Pick a name for the package => for this example we take `fire-theme`.
|
||||
2. Create a new folder `fire-theme`
|
||||
3. Create a folder `fire-theme/preset` copy `fireTheme.js` from [above](#create-a-preset-config-file) into `preset/fireTheme.js`
|
||||
4. Add a 👉 `package.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "fire-theme",
|
||||
"version": "0.3.0",
|
||||
"description": "Fire Theme for Rocket",
|
||||
"license": "MIT",
|
||||
"type": "module",
|
||||
"exports": {
|
||||
".": "./index.js",
|
||||
"./preset/": "./preset/"
|
||||
},
|
||||
"files": ["*.js", "preset"],
|
||||
"keywords": ["rocket", "preset"]
|
||||
}
|
||||
```
|
||||
|
||||
5. Add a 👉 `index.js`
|
||||
|
||||
```js
|
||||
export { fireTheme } from './preset/fireTheme.js';
|
||||
```
|
||||
|
||||
6. Add a 👉 `README.md`
|
||||
|
||||
````
|
||||
# FireTheme
|
||||
|
||||
This is a theme/preset for [Rocket](https://rocket.modern-web.dev/).
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
npm i -D fire-theme
|
||||
```
|
||||
|
||||
Add it to your 👉 `rocket.config.js`
|
||||
|
||||
```js
|
||||
import { fireTheme } from 'fire-theme';
|
||||
|
||||
export default {
|
||||
presets: [fireTheme()],
|
||||
};
|
||||
```
|
||||
````
|
||||
7
docs/guides/presets/getting-started.md
Normal file
7
docs/guides/presets/getting-started.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# Presets >> Getting Started ||10
|
||||
|
||||
Presets are ...
|
||||
|
||||
You can use a preset via the config...
|
||||
|
||||
You can load multiple presets.
|
||||
1
docs/guides/presets/index.md
Normal file
1
docs/guides/presets/index.md
Normal file
@@ -0,0 +1 @@
|
||||
# Presets || 20
|
||||
7
docs/guides/presets/overriding.md
Normal file
7
docs/guides/presets/overriding.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# Presets >> Overriding ||20
|
||||
|
||||
All loaded presets will be combined but you can override each file.
|
||||
|
||||
Take a look at `docs/_merged_includes` and override what you want to override by placing the same filename into `_includes`.
|
||||
|
||||
Also works for `_assets`, `_data` ...
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user