diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 888df101594d989..a4f9b4e008ca22d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,169 +1,9 @@ -# Contributing to Cloudflare's documentation +# Contributing to Cloudflare's developer documentation -Before contributing code to Cloudflare's documentation, please read the following guidelines carefully. +Everyone, including those who are not part of the Cloudflare organization, are encouraged to contribute. +- If you are not a Cloudflare employee, learn how to contribute in the [contribution page](https://developers.cloudflare.com/style-guide/contributions/) of the Cloudflare Style Guide. +- If you are a Cloudflare employee, reach out via our Developer Docs space in Google chat. -## Have feedback for our documentation? Open an issue +Consult the [Cloudflare Style Guide](https://developers.cloudflare.com/style-guide/) on everything from grammar, to formatting, to frontmatter requirements. Browse our [components](/style-guide/components/) to add additional formatting such as [notes](/style-guide/documentation-content-strategy/component-attributes/notes-tips-warnings/) and [code blocks](/style-guide/components/code/). -[Open an issue](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) when something in our documentation is incorrect, out-of-date, or if the documentation doesn’t match the actual functionality. - -## Before submitting a PR, open an issue - -Before proposing significant changes, such as adding a new page, [open an issue](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) so that we can discuss your approach first. Only members of the Cloudflare organization can open a pull request on the repository, and they should follow the same guidance on opening an issue for significant changes. If you’re not part of the Cloudflare organization but want to contribute, fork the repository and then create a pull request. - -A member of the Product Content Experience team will review the pull request. If the changes are straightforward, the pull request is approved and can be merged. If the pull request is more technical and requires an additional review, the new reviewer will leave any additional feedback. - -If a pull request is not approved, the “won't fix” label is applied and a comment is added to explain why the pull request was closed. - -If we require more information to address your pull request, the `more-information-needed` label will be applied to the pull request. If more information has not been provided within fourteen days, the pull request will automatically close. - -### Pull Request Guidelines - -- Commits and commit messages - - Use smaller commits for your work to make it easier to review. In your commit messages, be specific about what you changed in the files. - - If you are proposing a new page, review our [content type guidelines](https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/) for options and templates. -- Pull request titles - - Follow the title structure of [Product Name] + work you did + affected file(s) - - Example: [Access] fix broken link in example_file.md -- Pull request descriptions - - Use bullet points to summarize the changes in the commits - - Add any other information you think is helpful or needs to be addressed. If your PR fixes an open issue, indicate that your PR is addressing the issue and provide a link to the issue. - -## Package manager - -- [npm](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager#introduction-to-npm) is the recommended package manager that must be used in installing dependencies. -- The generated `package-lock.json` file must be committed to git. - -## Wrangler config - -If you are adding a code snippet to the docs that represents a Wrangler config file (`wrangler.toml`, `wrangler.json`, or `wrangler.jsonc`) make sure you wrap it with the `` component, which ensures it is rendered as both JSON and TOML. For example: - -```` - -import { WranglerConfig } from "~/components"; - - - -```toml -# Top-level configuration -name = "my-worker" -main = "src/index.js" -compatibility_date = "2022-07-12" - -workers_dev = false -route = { pattern = "example.org/*", zone_name = "example.org" } - -kv_namespaces = [ - { binding = "", id = "" } -] - -[env.staging] -name = "my-worker-staging" -route = { pattern = "staging.example.org/*", zone_name = "example.org" } - -kv_namespaces = [ - { binding = "", id = "" } -] -``` - - - -```` - -## Workers Playground - -If you are adding a code snippet to the docs that is: - -1. A fully contained, valid Worker (i.e. it does not require external dependencies or specific bindings) -2. Only JavaScript - -you can add `playground: true` to the code block metadata to render a button to let users open the Worker in the [Playground](https://workers.new). For example: - -```` -```js ---- -playground: true ---- -export default { - async fetch(request) { - /** - * Replace `remote` with the host you wish to send requests to - */ - const remote = "https://example.com"; - - return await fetch(remote, request); - }, -}; -``` -```` - -would render as - -Screenshot 2024-02-20 at 14 29 22 - -## GraphQL API Explorer - -If you are adding a code snippet to the documentation that is an executable GraphQL query, you can add `graphql-api-explorer` right after `graphql` in the code block metadata (both must be present). This will render a button that allows users to open the query in the [GraphQL API Explorer](https://graphql.cloudflare.com/explorer). For example: - -```` -```graphql graphql-api-explorer title="A GraphQL query" -query GraphqlExample($zoneTag: string, $start: Time, $end: Time) { - viewer { - zones(filter: { zoneTag: $zoneTag }) { - firewallEventsAdaptive( - filter: { datetime_gt: $start, datetime_lt: $end } - limit: 2 - orderBy: [datetime_DESC] - ) { - action - datetime - host: clientRequestHTTPHost - } - } - } -} -``` -```` - -When a user selects the `Run in GraphQL API Explorer` button, the following variables will be pre-populated in the GraphQL API Explorer along with the query. - -:::note -The user must be logged in or have an API token saved to see the query and variables pre-populated. -::: - -``` -{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z"} -``` - -### Conventions to auto populate `Variables` section in the GraphQL API Explorer - -By default, the `Variables` section will be automatically populated based on the variables used in the GraphQL query. - -- Any variable name that includes `start` and has a type of `Time` --> start: "2025-05-09T14:58:06Z" (6 hours from the current time) - - e.g. `datetimeStart` also has `start` keyword, so it will be recognized for a start time (or date) -- Any variable name that includes `end` and has a type of `Time` --> end: "2025-05-09T20:58:06Z" (current time) -- Any variable name that includes `start` and has a type of `Date` --> start: "2025-05-07" (24 hours from the current date) -- Any variable name that includes `end` and has a type of `Date` --> end: "2025-05-08" (current date) -- `zoneTag` and has a type of `string` --> zoneTag: "ZONE_ID" -- `accountTag` and has a type of `string` --> accountTag: "ACCOUNT_ID" -- Any variable name that includes `id` and has a type of `string` --> id: "REPLACE_WITH_ID" -- Any variable name and has a type of string --> anyString: "REPLACE_WITH_STRING" -- `limit` with type `*int*` --> limit: 100 - -In addition to the variables that are automatically populated, you can add custom variables by setting their values as a JSON string in the `graphql-api-explorer` metadata. - -```` -```graphql graphql-api-explorer='{"uID": "something"}' title="A GraphQL query" -query GraphqlExample($zoneTag: string, $start: Time, $end: Time) { - viewer { - zones(filter: { zoneTag: $zoneTag }) { - ... - } - } -} -```` - -The variables added via the metadata value will be merged with the automatically populated variables. - -``` -{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z", "uId": "something"} -``` +Thank you for helping us to maintain quality documentation. \ No newline at end of file diff --git a/README.md b/README.md index a8413e5d57fa69c..305365f1a553540 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,8 @@ -# Cloudflare Docs +# Cloudflare Developer Documentation -**[View the docs →](https://developers.cloudflare.com/)** +Welcome to the open-source repository for all [Cloudflare Developer Documentation](https://developers.cloudflare.com/). -## Why Cloudflare Docs is open source - -Our documentation is open source so that we can stay connected with our community and quickly implement feedback. Whether you have opened an issue to provide feedback or contributed your own content, we thank you for helping us maintain quality documentation. - -If you have any feedback for our documentation or are interested in contributing, please refer to our [contribution guidelines.](https://github.com/cloudflare/cloudflare-docs/blob/production/CONTRIBUTING.md) - -## Setup - -You must have a recent version of Node.js (22+) installed. You may use [Volta](https://github.com/volta-cli/volta), a Node version manager, to install the latest version of Node and `npm`, which is a package manager that is included with `node`'s installation. - -```sh -$ curl https://get.volta.sh | bash -$ volta install node@22 -``` - -Install the Node.js dependencies for this project using npm or another package manager: - -```sh -$ npm install -``` - -## Development - -When making changes to the site, including any content changes, you may run a local development server by running the following command: - -```sh -$ npm run dev -``` - -This spawns a server that will be accessible via `http://localhost:1111` in your browser. Additionally, any changes made within the project – including `content/**` changes – will automatically reload your browser tab(s), allowing you to instantly preview your changes. - -## Deployment - -Our docs are deployed using [Cloudflare Pages](https://pages.cloudflare.com). Every commit pushed to production will automatically deploy to [developers.cloudflare.com](https://developers.cloudflare.com), and any pull requests opened will have a corresponding staging URL available in the pull request comments. - -## For Cloudflare employees - -To get write access to this repo, please reach out to the **Developer Docs** room in chat. +To learn how to contribute, visit the [contribution page](https://developers.cloudflare.com/style-guide/contributions/) of the Cloudflare Style Guide. ## License and Legal Notices @@ -49,19 +12,3 @@ Cloudflare products and services referenced in the documentation may be either t Cloudflare and any contributors reserve all other rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel, or otherwise. Please note that we may use AI tools to help us review technical documentation, pull requests and other issues submitted to our public GitHub page in order to identify and correct mistakes and other inconsistencies in our developer documentation. Please refrain from sharing any personal information in your submissions. - - -## 🧞 Commands - -All commands are run from the root of the project, from a terminal: - -| Command | Action | -|:--------------------------|:--------------------------------------------| -| `npm install` | Installs dependencies | -| `npm run dev` | Starts local dev server at `localhost:1111` | -| `npx astro build` | Build your production site to `./dist/` | -| `npm run astro -- --help` | Get help using the Astro CLI | - -## 👀 Want to learn more? - -Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat). diff --git a/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx index 1a5d7606a4c1539..90766c730cba544 100644 --- a/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx +++ b/src/content/docs/ssl/post-quantum-cryptography/pqc-support.mdx @@ -7,7 +7,7 @@ head: [] description: Consider information about post-quantum cryptography at Cloudflare - deployed key agreements and software support. --- -Cloudflare's deployment of post-quantum [hybrid key agreements](/ssl/post-quantum-cryptography/#hybrid-key-agreement) is supported by different software as listed below. [Contributions](https://github.com/cloudflare/cloudflare-docs/blob/production/CONTRIBUTING.md) to keep the listing up-to-date are welcome! +Cloudflare's deployment of post-quantum [hybrid key agreements](/ssl/post-quantum-cryptography/#hybrid-key-agreement) is supported by different software as listed below. [Contributions](/style-guide/contributions/) to keep the listing up-to-date are welcome. :::caution The list below is for reference only. Responsibility for third-party software lies with their respective maintainers. Use them at your own discretion. diff --git a/src/content/docs/style-guide/index.mdx b/src/content/docs/style-guide/index.mdx index 316b70591e6765d..4c8e3d694a3a430 100644 --- a/src/content/docs/style-guide/index.mdx +++ b/src/content/docs/style-guide/index.mdx @@ -17,7 +17,7 @@ Understanding Cloudflare style is the first step in being able to write, review, - Minimized customer confusion - Simplified translation process -Visit the [Cloudflare Docs](https://github.com/cloudflare/cloudflare-docs) repository to contribute to developer documentation. +To contribute to the documentation, visit the [contributor guide](/style-guide/contributions/). ## Available resources diff --git a/src/content/docs/turnstile/community-resources.mdx b/src/content/docs/turnstile/community-resources.mdx index ad074b6a767b9f0..544e35fc48164fc 100644 --- a/src/content/docs/turnstile/community-resources.mdx +++ b/src/content/docs/turnstile/community-resources.mdx @@ -17,9 +17,7 @@ As such, Cloudflare is not liable for any damages arising from using them. :::note -Did we miss your library? [Contribute to our list][1]. - -[1]: https://github.com/cloudflare/cloudflare-docs/blob/production/CONTRIBUTING.md#pull-request-guidelines +Did we miss your library? [Contribute to our list](/style-guide/contributions/) ::: diff --git a/src/plugins/expressive-code/graphql-api-explorer.js b/src/plugins/expressive-code/graphql-api-explorer.js index c01958f10d1737c..67af4da28955487 100644 --- a/src/plugins/expressive-code/graphql-api-explorer.js +++ b/src/plugins/expressive-code/graphql-api-explorer.js @@ -11,7 +11,7 @@ async function compressGql(gql) { } /** - * See CONTRIBUTING.md for instructions on how to use this plugin. + * See https://developers.cloudflare.com/style-guide/contributions/ for instructions on how to use this plugin. * @param {string} query */ function autoPopulateGraphQLVariables(query) {