diff --git a/.github/workflows/auto-cleanup-bot.yml b/.github/workflows/auto-cleanup-bot.yml index 25861b4ad0da310..485f6b7a7207600 100644 --- a/.github/workflows/auto-cleanup-bot.yml +++ b/.github/workflows/auto-cleanup-bot.yml @@ -34,7 +34,7 @@ jobs: - name: Create PR with only fixable issues if: success() - uses: peter-evans/create-pull-request@v6 + uses: peter-evans/create-pull-request@v7 with: commit-message: "chore: auto-fix Markdownlint, Prettier, and front-matter issues" branch: markdownlint-auto-cleanup @@ -49,7 +49,7 @@ jobs: - name: Create PR with notice on unfixed issues if: failure() - uses: peter-evans/create-pull-request@v6 + uses: peter-evans/create-pull-request@v7 with: commit-message: "chore: auto-fix Markdownlint, Prettier, and front-matter issues" branch: markdownlint-auto-cleanup diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml index 5a206ab3ad6509b..c0930e006765243 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/auto-merge.yml @@ -6,7 +6,7 @@ on: jobs: auto-merge: runs-on: ubuntu-latest - if: github.actor == 'dependabot[bot]' + if: github.event.pull_request.user.login == 'dependabot[bot]' steps: - uses: ahmadnassri/action-dependabot-auto-merge@v2.6 with: diff --git a/.github/workflows/interfacedata-updater.yml b/.github/workflows/interfacedata-updater.yml index 1ba2d59f2dd6404..a188d4dcd7bf989 100644 --- a/.github/workflows/interfacedata-updater.yml +++ b/.github/workflows/interfacedata-updater.yml @@ -35,7 +35,7 @@ jobs: run: node scripts/update-interface-data.js ../webref/ - name: Create pull request - uses: peter-evans/create-pull-request@v6 + uses: peter-evans/create-pull-request@v7 with: path: mdn-content token: ${{ secrets.AUTOMERGE_TOKEN }} diff --git a/.github/workflows/pr-check-lint_content.yml b/.github/workflows/pr-check-lint_content.yml index 6ba2a4950251e8d..a505197e579fac8 100644 --- a/.github/workflows/pr-check-lint_content.yml +++ b/.github/workflows/pr-check-lint_content.yml @@ -32,7 +32,7 @@ jobs: run: | # Use the GitHub API to get the list of changed files # documentation: https://docs.github.com/rest/commits/commits#compare-two-commits - DIFF_DOCUMENTS=$(gh api repos/{owner}/{repo}/compare/${{ env.BASE_SHA }}...${{ env.HEAD_SHA }} \ + DIFF_DOCUMENTS=$(gh api repos/{owner}/{repo}/compare/${BASE_SHA}...${HEAD_SHA} \ --jq '.files | .[] | select(.status|IN("added", "modified", "renamed", "copied", "changed")) | .filename') # filter out files that are not markdown DIFF_DOCUMENTS=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.md$" | xargs) diff --git a/.github/workflows/pr-test.yml b/.github/workflows/pr-test.yml index 51a23553a9cafb2..3d39964e3c0dfa0 100644 --- a/.github/workflows/pr-test.yml +++ b/.github/workflows/pr-test.yml @@ -34,7 +34,7 @@ jobs: run: | # Use the GitHub API to get the list of changed files # documentation: https://docs.github.com/rest/commits/commits#compare-two-commits - DIFF_DOCUMENTS=$(gh api repos/{owner}/{repo}/compare/${{ env.BASE_SHA }}...${{ env.HEAD_SHA }} \ + DIFF_DOCUMENTS=$(gh api repos/{owner}/{repo}/compare/${BASE_SHA}...${HEAD_SHA} \ --jq '.files | .[] | select(.status|IN("added", "modified", "renamed", "copied", "changed")) | .filename') # filter out files that are not markdown files @@ -97,27 +97,27 @@ jobs: # you don't need that script as a writer. It's only used in CI # and it can't use the default CONTENT_ROOT that gets set in # package.json. - yarn build ${{ env.GIT_DIFF_CONTENT }} + yarn build $GIT_DIFF_CONTENT echo "Disk usage size of the build" - du -sh ${{ env.BUILD_OUT_ROOT }} + du -sh $BUILD_OUT_ROOT # Save the PR number into the build - echo ${{ github.event.number }} > ${{ env.BUILD_OUT_ROOT }}/NR + echo ${{ github.event.number }} > ${BUILD_OUT_ROOT}/NR # Download the raw diff blob and store that inside the build # directory. # The purpose of this is for the PR Review Companion to later # be able to use this raw diff file for the benefit of analyzing. - wget https://github.com/${{ github.repository }}/compare/${{ env.BASE_SHA }}...${{ env.HEAD_SHA }}.diff -O ${{ env.BUILD_OUT_ROOT }}/DIFF + wget https://github.com/${{ github.repository }}/compare/${BASE_SHA}...${HEAD_SHA}.diff -O ${BUILD_OUT_ROOT}/DIFF - name: Merge static assets with built documents if: ${{ env.GIT_DIFF_CONTENT }} run: | # Exclude the .map files, as they're used for debugging JS and CSS. - rsync -a --exclude "*.map" node_modules/@mdn/yari/client/build/ ${{ env.BUILD_OUT_ROOT }} + rsync -a --exclude "*.map" node_modules/@mdn/yari/client/build/ $BUILD_OUT_ROOT # Show the final disk usage size of the build. - du -sh ${{ env.BUILD_OUT_ROOT }} + du -sh $BUILD_OUT_ROOT - uses: actions/upload-artifact@v4 if: ${{ env.GIT_DIFF_CONTENT }} @@ -128,7 +128,7 @@ jobs: - name: Check changed files if: ${{ env.GIT_DIFF_FILES }} run: | - echo ${{ env.GIT_DIFF_FILES }} + echo $GIT_DIFF_FILES export CONTENT_ROOT=$(pwd)/files - yarn filecheck ${{ env.GIT_DIFF_FILES }} + yarn filecheck $GIT_DIFF_FILES diff --git a/.github/workflows/spelling-check-bot.yml b/.github/workflows/spelling-check-bot.yml new file mode 100644 index 000000000000000..cc04cb4776acc40 --- /dev/null +++ b/.github/workflows/spelling-check-bot.yml @@ -0,0 +1,54 @@ +name: Create an issue to report typos + +on: + schedule: + - cron: "0 0 * * mon" + workflow_dispatch: + +jobs: + sync: + if: github.repository == 'mdn/content' + runs-on: ubuntu-latest + permissions: + issues: write + + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js environment + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: yarn + + - name: Run scripts + run: | + echo Running spelling check... + output=$(npx cspell --no-progress --gitignore --config .vscode/cspell.json "**/*.md" || exit 0) + if [ -n "${output}" ]; then + output=$(node scripts/linkify-logs.js "${output}") + output=$(echo "$output" | sed 's/^/- /') + echo "$output" + echo "OUTPUT<> $GITHUB_ENV + echo "$output" >> $GITHUB_ENV + echo "EOF" >> $GITHUB_ENV + else + echo "No typos found! 🎉" + fi + + - name: Report spellcheck errors + if: env.OUTPUT != '' + run: | + issue=$(gh issue create --title "$TITLE" --label "$LABELS" --body "$BODY") + echo Issue URL ${issue} + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TITLE: Weekly spelling check + LABELS: reported by automation,good first issue + BODY: | + Typos and unknown words: + + ${{ env.OUTPUT }} + + > [!TIP] + > To exclude words from the spellchecker, you can add valid words (web technology terms or abbreviations) to the [terms-abbreviations.txt](https://github.com/mdn/content/blob/main/.vscode/terms-abbreviations.txt) dictionary for IDE autocompletion. To ignore strings that are not words (\`AABBCC\` in code, for instance), you can add them to [ignore-list.txt](https://github.com/mdn/content/blob/main/.vscode/ignore-list.txt). diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 0e7391244b949f4..6d39a7623bd6a12 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -3,7 +3,10 @@ "version": "0.2", "language": "en-US", "languageId": "*", + "useGitignore": true, "dictionaries": [ + "terms-abbreviations", + "ignore-list", "bash", "css", "cpp", @@ -17,7 +20,6 @@ "markdown", "node", "npm", - "project-words", "python", "softwareTerms", "svelte", @@ -37,10 +39,9 @@ // TODO - add some details what these match "\\(#\\w*\\)", "\\]\\(\\S*\\)", - "\\]\\(\\S*\\)", "\\*\\*\\w\\*\\*\\w*", "\\*\\w\\*\\w*", - "#[\\w-]*", + "#[À-ž\\w-]*", "aria-activedescendant=\"(?:[^\\\"]+|\\.)*\"", "aria-controls=\"(?:[^\\\"]+|\\.)*\"", "aria-describedby=\"(?:[^\\\"]+|\\.)*\"", @@ -55,18 +56,26 @@ "for=\"(?:[^\\\"]+|\\.)*\"", "HexValues", "href=\"(?:[^\\\"]+|\\.)*\"", - "id=\"(?:[^\\\"]+|\\.)*\"", + "(?<=id)=\"(?:[^\\\"]+|\\.)*\"", "lang=\".*\">.* [!NOTE] +> There is some overlap between content headers and {{Glossary("Representation header", "representation headers")}}. + +These headers may be present in both HTTP request and response messages and include: + +- {{HTTPHeader("Content-Encoding")}} +- {{HTTPHeader("Content-Length")}} +- {{HTTPHeader("Content-Range")}} +- {{HTTPHeader("Content-Type")}} +- {{HTTPHeader("Trailer")}} +- {{HTTPHeader("Transfer-Encoding")}} + +## See also + +- [HTTP headers](/en-US/docs/Web/HTTP/Headers) +- Related glossary terms: + - {{Glossary("Representation header")}} + - {{Glossary("HTTP Content")}} +- [RFC 9110, section 6.4.1: Content semantics](https://httpwg.org/specs/rfc9110.html#rfc.section.6.4.1), specifically [Appendix B.3.: Changes from RFC 7231](https://httpwg.org/specs/rfc9110.html#changes.from.rfc.7231) +- [RFC 7231, section 3.3: Payload Semantics](https://datatracker.ietf.org/doc/html/rfc7231#section-3.3) diff --git a/files/en-us/glossary/css_preprocessor/index.md b/files/en-us/glossary/css_preprocessor/index.md index ae5642b82ec3709..28e6e0ba8c5a555 100644 --- a/files/en-us/glossary/css_preprocessor/index.md +++ b/files/en-us/glossary/css_preprocessor/index.md @@ -19,7 +19,6 @@ To use a CSS preprocessor, you must install a CSS compiler on your web {{Glossar - [Sass](https://sass-lang.com/) - [LESS](https://lesscss.org/) - [Stylus](https://stylus-lang.com/) - - [PostCSS](https://postcss.org/) - Related glossary terms: - {{Glossary("CSS")}} diff --git a/files/en-us/glossary/debounce/index.md b/files/en-us/glossary/debounce/index.md new file mode 100644 index 000000000000000..75cb949fb4fd5b3 --- /dev/null +++ b/files/en-us/glossary/debounce/index.md @@ -0,0 +1,26 @@ +--- +title: Debounce +slug: Glossary/Debounce +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +**Debouncing**, in the context of programming, means to "batch" all operations requested during a specific interval into a single invocation. + +Debouncing is very similar to {{glossary("throttle", "throttling")}}. The key difference is that throttling enforces limits on continuous operations, while debouncing waits for invocations to stop for a specific time to consolidate many noisy invocations into one single invocation. + +A typical use case of debouncing is when responding to user input. When the user is typing, no other action should be taken to avoid the UI becoming laggy. When the user pauses typing, we can start processing the input, such as filtering results, giving suggestions, etc. If the function `search` is debounced by 10 milliseconds, it means: + +1. The first call to `search` is known as the _leading edge_. +2. For every next call to `search`, if it is within 10 milliseconds from the previous call, it is in the same "batch" as the previous call. +3. After 10 milliseconds have elapsed from the last call to `search`, if no other calls have happened, we have reached the _trailing edge_. + +Usually, `search` is executed once on the trailing edge only, although sometimes it might be executed on the leading edge, or even both edges, depending on the specific use case. If executed on both edges, the debouncing implementation usually also ensures that the next leading edge invocation doesn't fire at least 10 milliseconds after the previous trailing edge. + +## See also + +- Glossary terms: + - {{Glossary("Throttle")}} + - {{Glossary("Rate limit")}} +- [Debouncing and Throttling Explained Through Examples](https://css-tricks.com/debouncing-throttling-explained-examples/) on CSS-Tricks (April 6, 2016) diff --git a/files/en-us/glossary/doctype/index.md b/files/en-us/glossary/doctype/index.md index 5f8b8902b4e8ddc..18ba29e8af42019 100644 --- a/files/en-us/glossary/doctype/index.md +++ b/files/en-us/glossary/doctype/index.md @@ -6,7 +6,9 @@ page-type: glossary-definition {{GlossarySidebar}} -In {{Glossary("HTML")}}, the **doctype** is the required "``" preamble found at the top of all documents. Its sole purpose is to prevent a {{Glossary("browser")}} from switching into so-called ["quirks mode"](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) when rendering a document; that is, the "``" doctype ensures that the browser makes a best-effort attempt at following the relevant specifications, rather than using a different rendering mode that is incompatible with some specifications. +In {{Glossary("HTML")}}, the **doctype** is the required `` preamble found at the top of all documents. Its sole purpose is to prevent a {{Glossary("browser")}} from switching into so-called ["quirks mode"](/en-US/docs/Web/HTML/Quirks_Mode_and_Standards_Mode) when rendering a document; that is, the `` doctype ensures that the browser makes a best-effort attempt at following the relevant specifications, rather than using a different rendering mode that is incompatible with some specifications. + +The doctype is case-insensitive. The convention of MDN code examples is to use lowercase, but it's also common to write it as ``. ## See also diff --git a/files/en-us/glossary/entity_header/index.md b/files/en-us/glossary/entity_header/index.md index c59843a0a3543d1..dc5698d0773e74c 100644 --- a/files/en-us/glossary/entity_header/index.md +++ b/files/en-us/glossary/entity_header/index.md @@ -9,7 +9,7 @@ page-type: glossary-definition > [!WARNING] > The current HTTP/1.1 specification no longer refers to entities, entity headers or entity-body. Some of the fields are now referred to as {{glossary("Representation header")}} fields. -An entity header is an {{glossary("HTTP_header", "HTTP header")}} that describes the payload of an HTTP message (i.e. metadata about the message body). Entity headers include: {{HTTPHeader("Content-Length")}}, {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Encoding")}}, {{HTTPHeader("Content-Type")}}, {{HTTPHeader("Expires")}}, etc. Entity headers may be present in both HTTP request and response messages. +An entity header is an {{glossary("HTTP_header", "HTTP header")}} that describes the {{Glossary("HTTP content", "content")}} of an HTTP message (i.e. metadata about the message body). Entity headers include: {{HTTPHeader("Content-Length")}}, {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Encoding")}}, {{HTTPHeader("Content-Type")}}, {{HTTPHeader("Expires")}}, etc. Entity headers may be present in both HTTP request and response messages. In the following example, {{HTTPHeader("Content-Length")}} is an entity header, while {{HTTPHeader("Host")}} and {{HTTPHeader("User-Agent")}} are requests headers: diff --git a/files/en-us/glossary/etld/index.md b/files/en-us/glossary/etld/index.md index ae3d5d934bfcfbd..761aaaacc0b057f 100644 --- a/files/en-us/glossary/etld/index.md +++ b/files/en-us/glossary/etld/index.md @@ -22,7 +22,7 @@ However, this does not work as a general rule, because many registrars allow org Because this is a matter of the registrar's policies, it's impossible to tell algorithmically whether a given domain name suffix (like `ac.uk`) is publicly registrable or not. The [Public Suffix List](https://publicsuffix.org/) is a list of all suffixes under which organizations can directly register names: that is, it is a list of eTLDs. -The related concept **eTLD+1** means an eTLD plus the next part of the domain name. Because eTLDs are registrable, all domains with the same eTLD+1 are owned by the same organization. +The related concept **eTLD+1** means an eTLD plus the next part of the domain name. Because eTLD+1s are registrable, all domains with the same eTLD+1 are owned by the same organization. For example, all the following are eTLD+1 domains: diff --git a/files/en-us/glossary/http_content/index.md b/files/en-us/glossary/http_content/index.md new file mode 100644 index 000000000000000..44a0a0835c393f6 --- /dev/null +++ b/files/en-us/glossary/http_content/index.md @@ -0,0 +1,51 @@ +--- +title: HTTP Content +slug: Glossary/HTTP_Content +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +In HTTP messages, the **content** describes the 'information' conveyed in the message body (which follows the header section), after any message framing from HTTP/1.1 chunked transfer encoding has been removed. +This was referred to as a "payload" in HTTP/1.1, but message "content" distinguishes from frame payloads in HTTP/2 and HTTP/3 where the data in a single frame could be header data, body data, or other control information. + +The purpose of message content in HTTP requests and responses depends on the request method and response status code. +For example, in a {{HTTPMethod("PUT")}} request, the content represents the desired state of the resource, but in a {{HTTPMethod("POST")}} request, it is information to be processed. +A {{HTTPStatus("200", "200 OK")}} response to a {{HTTPMethod("GET")}} request shows the current state of the resource, while an error response describes the error. + +Some responses, like those to {{HTTPMethod("HEAD")}} requests or {{HTTPStatus("204", "204 No Content")}} and {{HTTPStatus("204", "304 Not Modified")}} status codes, do not include content at all. + +In the following HTTP/1.1 response, the message body contains the content `Mozilla Developer Network`: + +```http +HTTP/1.1 200 OK +Content-Type: text/plain + +Mozilla Developer Network +``` + +In the next HTTP/1.1 response, transfer encoding encodes the data into chunks. +The content is still `Mozilla Developer Network` in the end, but the message body includes different message data to separate the chunks: + +```http +HTTP/1.1 200 OK +Content-Type: text/plain +Transfer-Encoding: chunked + +7\r\n +Mozilla\r\n +9\r\n +Developer\r\n +7\r\n +Network\r\n +0\r\n +\r\n +``` + +## See also + +- {{HTTPHeader("Content-Location")}} +- {{HTTPStatus("413", "413 Content Too Large")}} +- {{Glossary("Content header")}} +- [RFC 9110, section 6.4: Content](https://httpwg.org/specs/rfc9110.html#rfc.section.6.4) (obsoletes [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-3.3) Payload Semantics) + - [Changes from RFC 7231](https://httpwg.org/specs/rfc9110.html#changes.from.rfc.7231) diff --git a/files/en-us/glossary/https_rr/index.md b/files/en-us/glossary/https_rr/index.md index 8cfe55e42bd0da4..6c8f3a1e633fad6 100644 --- a/files/en-us/glossary/https_rr/index.md +++ b/files/en-us/glossary/https_rr/index.md @@ -13,7 +13,7 @@ Further, the presence of an _HTTPS RR_ signals that all useful {{Glossary("HTTP" ### See also -- [Service binding and parameter specification via the DNS (DNS SVCB and HTTPS RRs)](https://datatracker.ietf.org/doc/draft-ietf-dnsop-svcb-https/00/) (Draft IETF specification: draft-ietf-dnsop-svcb-https-00) +- {{RFC(9460, "Service Binding and Parameter Specification via the DNS (SVCB and HTTPS Resource Records)")}} - [Strict Transport Security vs. HTTPS Resource Records: the showdown](https://emilymstark.com/2020/10/24/strict-transport-security-vs-https-resource-records-the-showdown.html) (Emily M. Stark blog) - Related glossary terms: - {{glossary("TLS")}} diff --git a/files/en-us/glossary/rate_limit/index.md b/files/en-us/glossary/rate_limit/index.md new file mode 100644 index 000000000000000..ef949672c1d98b6 --- /dev/null +++ b/files/en-us/glossary/rate_limit/index.md @@ -0,0 +1,19 @@ +--- +title: Rate limit +slug: Glossary/Rate_limit +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +In computing, especially in networking, **rate limiting** means controlling how many operations can be performed in a given amount of time, usually to avoid overloading the system and causing performance degredation. For example, a server might limit the number of requests it will accept from a single client in a given time period, which not only optimizes the server's overall performance but also mitigates attacks like {{glossary("DoS attack")}}. + +Rate limiting is typically synonymous with {{glossary("throttle", "throttling")}}, although {{glossary("debounce", "debouncing")}} is another viable strategy which provides better semantics and user experience in certain cases. + +## See also + +- Glossary terms: + - {{Glossary("Debounce")}} + - {{Glossary("Throttle")}} +- {{HTTPStatus("429", "429 Too Many Requests")}} +- [What is rate limiting? | Rate limiting and bots](https://www.cloudflare.com/en-gb/learning/bots/what-is-rate-limiting/) on cloudflare.com diff --git a/files/en-us/glossary/representation_header/index.md b/files/en-us/glossary/representation_header/index.md index ed230c66c985041..183574e19fac551 100644 --- a/files/en-us/glossary/representation_header/index.md +++ b/files/en-us/glossary/representation_header/index.md @@ -6,11 +6,10 @@ page-type: glossary-definition {{GlossarySidebar}} -A **representation header** is an {{glossary("HTTP_header", "HTTP header")}} that describes one particular _representation_ of a resource. +A **representation header** (or 'representation metadata') is an {{glossary("HTTP_header", "HTTP header")}} that describes how to interpret the data contained in the message. -Representations are different forms of a particular resource. - -For example, the same data might be formatted as a particular media type such as XML, JSON, HTML or Markdown, or localized to a particular written language or geographical region. +For example, the content in a particular message might be encoded for transport, the whole resource might be formatted as a particular media type such as XML, JSON, HTML or Markdown, localized to a particular written language or geographical region, and/or compressed using a particular algorithm. +The representation headers allow the underlying data to be extracted and understood. The underlying resource is semantically the same in each case, but its representation is different. While representations are different forms of resources, representations can themselves also be transmitted in various forms: an HTTP message frames (cf., e.g., HTTP/1.1's {{HTTPHeader("Transfer-Encoding")}}), a particular stream of octets (cf., e.g., {{HTTPHeader("Content-Range")}}) derived from the _selected representation_. @@ -20,15 +19,27 @@ Clients specify the formats that they prefer to be sent during [Content Negotiat Representation headers may be present in both HTTP request and response messages with various methods. If sent as a response to a `HEAD` request, they describe the body content representation that _would_ be selected if the resource was requested with a `GET` request. -Representation headers include: {{HTTPHeader("Content-Type")}}, {{HTTPHeader("Content-Encoding")}}, {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Range")}}, {{HTTPHeader("Repr-Digest")}}, and {{HTTPHeader("Digest")}} {{Deprecated_Inline}}. +Representation headers include: + +- {{HTTPHeader("Content-Length")}} +- {{HTTPHeader("Content-Range")}} +- {{HTTPHeader("Content-Type")}} +- {{HTTPHeader("Content-Encoding")}} +- {{HTTPHeader("Content-Location")}} +- {{HTTPHeader("Content-Language")}} + +- Validators used in [conditional requests](/en-US/docs/Web/HTTP/Conditional_requests), such as: + - {{HTTPHeader("Last-Modified")}} + - {{HTTPHeader("ETag")}} + +Representation headers are not mutually exclusive with {{Glossary("Content header", "content headers")}}. ## See also - [RFC 9110, section 3.2: Representations](https://httpwg.org/specs/rfc9110.html#representations) - [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers) - Related glossary terms: - - {{Glossary("Payload header")}} - - {{glossary("Entity header")}} + - {{Glossary("Content header")}} - {{HTTPHeader("Repr-Digest")}}, {{HTTPHeader("Want-Repr-Digest")}} - {{HTTPHeader("Content-Digest")}}, {{HTTPHeader("Want-Content-Digest")}} - {{HTTPHeader("Digest")}} {{Deprecated_Inline}}, {{HTTPHeader("Want-Digest")}} {{Deprecated_Inline}} diff --git a/files/en-us/glossary/slug/index.md b/files/en-us/glossary/slug/index.md index b827a5b08d0b62f..b90c8d213ab5b05 100644 --- a/files/en-us/glossary/slug/index.md +++ b/files/en-us/glossary/slug/index.md @@ -8,7 +8,7 @@ page-type: glossary-definition A Slug is the unique identifying part of a web address, typically at the end of the URL. In the context of MDN, it is the portion of the URL following "_\/docs/_". -It may also just be the final component when a new document is created under a parent document; for example, this page's slug is `Glossary/Slug` . +It may also just be the final component when a new document is created under a parent document; for example, this page's slug is `Glossary/Slug`. ## See also diff --git a/files/en-us/glossary/ssg/index.md b/files/en-us/glossary/ssg/index.md new file mode 100644 index 000000000000000..07c194a863f7032 --- /dev/null +++ b/files/en-us/glossary/ssg/index.md @@ -0,0 +1,22 @@ +--- +title: Static site generator (SSG) +slug: Glossary/SSG +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +A **static site generator** (SSG) is a software used to generate _static_ websites. A static website is comprised of {{glossary("HTML")}}, {{glossary("CSS")}}, and {{glossary("JavaScript")}} files. Most importantly static sites do not have [server-side logic](/en-US/docs/Learn/Server-side), so for any given URL, all users will receive the same content. Authors write content in any form accepted by the generator, such as Markdown, reStructuredText, HTML, (and sometimes even [React](/en-US/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/React_getting_started), and so on), and the generator compiles them into a set of optimized static files that can be rendered by the browser. + +Static sites are commonly used for blogs, documentation, and other content-driven websites, which don't have data that needs to be fetched or generated server-side. They are fast, secure, and easy to deploy, because they can be served from a {{glossary("CDN")}}. + +## See also + +- [Introduction to client-side frameworks > static site generators](/en-US/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/Introduction#static_site_generators) +- [Static site generator](https://en.wikipedia.org/wiki/Static_site_generator) on Wikipedia +- [Wordpress](https://wordpress.com/) +- [Docusaurus](https://docusaurus.io/) +- [Jekyll](https://jekyllrb.com/) +- [Astro](https://astro.build/) +- [VitePress](https://vitepress.dev/) +- [Eleventy](https://www.11ty.dev/) diff --git a/files/en-us/glossary/statement/index.md b/files/en-us/glossary/statement/index.md index 240242b297efafc..837c26851883522 100644 --- a/files/en-us/glossary/statement/index.md +++ b/files/en-us/glossary/statement/index.md @@ -10,5 +10,5 @@ In a computer programming language, a **statement** is a line of code commanding ## See also -- [Statement (computer science)]() on Wikipedia - [JavaScript statements and declarations](/en-US/docs/Web/JavaScript/Reference/Statements) +- [Statement (computer science)]() on Wikipedia diff --git a/files/en-us/glossary/throttle/index.md b/files/en-us/glossary/throttle/index.md new file mode 100644 index 000000000000000..28d5d1388998db1 --- /dev/null +++ b/files/en-us/glossary/throttle/index.md @@ -0,0 +1,30 @@ +--- +title: Throttle +slug: Glossary/Throttle +page-type: glossary-definition +--- + +{{GlossarySidebar}} + +**Throttling** originally meant slowing down the rate of fluid flow using an obstruction. In the context of programming, it refers to slowing down a process such that an operation can only be performed at a certain rate. + +Throttling is very similar to {{glossary("debounce", "debouncing")}}. The key difference is that when invocations happen continuously, throttling ensures that the operation is still performed at a certain maximum rate, while debouncing waits indefinitely until the invocations stop for a certain amount of time. + +A typical use case of throttling is when synchronizing with another constantly-updating state. Consider a function `onScrolled`, which listens for the [`scroll`](/en-US/docs/Web/API/Document/scroll_event) event. The `scroll` event may fire as often as every pixel scrolled, so the function will be called in very short intervals. If `onScrolled` is computationally expensive, earlier invocations might block later invocations from happening on time, or block other things from executing in the meantime, leading to a noticeable {{glossary("jank")}}. In this case, we can throttle `onScrolled`, such that it can only be called at most once every 10 milliseconds: + +1. The first call to `onScrolled` is known as the _leading edge_. +2. For every next call to `onScrolled`, if it is within 10 milliseconds from the first call, it is in the same "batch" as the first call. +3. After 10 milliseconds have elapsed from the first call to `onScrolled`, we have reached the _trailing edge_. + +Usually, `onScrolled` is executed once on the leading edge only, although sometimes it might be executed on the trailing edge, or even both edges, depending on the specific use case. If executed on both edges, the throttling implementation usually also ensures that the next leading edge invocation doesn't fire at least 10 milliseconds after the previous trailing edge. + +Via throttling, the effect of `onScrolled` is still continuously updated and applied — for example, if it moves another DOM element based on the document's scroll position, that DOM element is still continuously moved while the page is scrolling — but it isn't executed more often than necessary. + +{{glossary("Network throttling")}} means to simulate a slower network connection by only allowing a certain amount of data to be transferred at a time. _Throttling a timer_ means to coarsen the timer's precision such that when reading the timer (such as {{jsxref("Date.now()")}}) continuously, the timer's value only changes at a certain maximum rate. Both are specific applications of the general concept of throttling. + +## See also + +- Glossary terms: + - {{Glossary("Debounce")}} + - {{Glossary("Rate limit")}} +- [Debouncing and Throttling Explained Through Examples](https://css-tricks.com/debouncing-throttling-explained-examples/) on CSS-Tricks (April 6, 2016) diff --git a/files/en-us/learn/common_questions/tools_and_setup/available_text_editors/index.md b/files/en-us/learn/common_questions/tools_and_setup/available_text_editors/index.md index df2d6daeb3cdcae..e126e9834669516 100644 --- a/files/en-us/learn/common_questions/tools_and_setup/available_text_editors/index.md +++ b/files/en-us/learn/common_questions/tools_and_setup/available_text_editors/index.md @@ -92,7 +92,7 @@ Here are some popular editors: Yes @@ -104,8 +104,8 @@ Here are some popular editors: $99 Mac - Twitter, - Forum, + Twitter, + Forum, Online eBook @@ -150,7 +150,7 @@ Here are some popular editors: Yes - Espresso + Espresso Closed source $99 Mac @@ -192,23 +192,6 @@ Here are some popular editors: Yes - - - Komodo Edit - - MPL - Free - Windows, Mac, Linux - Forum - - Online Manual - - Yes - Windows, Mac, Linux Forum @@ -269,7 +252,7 @@ Here are some popular editors: Unofficial - Yes + Yes TextMate @@ -277,20 +260,17 @@ Here are some popular editors: $50 Mac - Twitter, + Twitter, IRC, - Mailing list, Email - Online Manual, - Wiki + Online Manual - Yes @@ -428,7 +408,7 @@ If you like _lots_ of features and your editor is slowing down because of all yo - [Aptana Studio](https://www.axway.com/en/aptana) - [Eclipse](https://www.eclipse.org/) - [Komodo IDE](https://www.activestate.com/products/komodo-ide/) -- [NetBeans IDE](https://netbeans.apache.org//) +- [NetBeans IDE](https://netbeans.apache.org/) - [Visual Studio](https://visualstudio.microsoft.com/) - [WebStorm](https://www.jetbrains.com/webstorm/) diff --git a/files/en-us/learn/common_questions/tools_and_setup/how_much_does_it_cost/index.md b/files/en-us/learn/common_questions/tools_and_setup/how_much_does_it_cost/index.md index 77d4661f8fbeff3..615986cfee0b38a 100644 --- a/files/en-us/learn/common_questions/tools_and_setup/how_much_does_it_cost/index.md +++ b/files/en-us/learn/common_questions/tools_and_setup/how_much_does_it_cost/index.md @@ -46,7 +46,7 @@ When launching a website, you may spend nothing, or your costs may go through th You likely have a text editor: such as, Notepad on Windows, Gedit on Linux, TextEdit on Mac. You'll have an easier time writing code if you choose an editor that color-codes, checks your syntax, and assists you with code structure. -Many editors are free, for example [Brackets](https://brackets.io/), [Bluefish](https://bluefish.openoffice.nl/index.html), [TextWrangler](https://www.barebones.com/products/textwrangler/), [Eclipse](https://www.eclipse.org/), [Netbeans](https://netbeans.apache.org//), and [Visual Studio Code](https://code.visualstudio.com/). Some, like [Sublime Text](https://www.sublimetext.com/), you can test as long as you like, but you're encouraged to pay. Some, like [PhpStorm](https://www.jetbrains.com/phpstorm/), can cost between a few dozen and 200 dollars, depending on the plan you purchase. Some of them, like [Microsoft Visual Studio](https://visualstudio.microsoft.com/), can cost hundreds, or thousands of dollars; though Visual Studio Community is free for individual developers or open source projects. Often, for-pay editors will have a trial version. +Many editors are free, for example [Brackets](https://brackets.io/), [Bluefish](https://bluefish.openoffice.nl/index.html), [TextWrangler](https://www.barebones.com/products/textwrangler/), [Eclipse](https://www.eclipse.org/), [Netbeans](https://netbeans.apache.org/), and [Visual Studio Code](https://code.visualstudio.com/). Some, like [Sublime Text](https://www.sublimetext.com/), you can test as long as you like, but you're encouraged to pay. Some, like [PhpStorm](https://www.jetbrains.com/phpstorm/), can cost between a few dozen and 200 dollars, depending on the plan you purchase. Some of them, like [Microsoft Visual Studio](https://visualstudio.microsoft.com/), can cost hundreds, or thousands of dollars; though Visual Studio Community is free for individual developers or open source projects. Often, for-pay editors will have a trial version. To start, we suggest trying out several editors, to get a sense of which works best for you. If you're only writing simple {{Glossary("HTML")}}, {{Glossary("CSS")}}, and {{Glossary("JavaScript")}}, go with a simple editor. @@ -64,7 +64,7 @@ You can use any of them, as they will have similar functionality, though some ar If you want to include video or audio into your website, you can either embed online services (for example YouTube, Vimeo, or Dailymotion), or include your own videos (see below for bandwidth costs). -For audio files, you can find free software ([Audacity](https://www.audacityteam.org/), [Wavosaur](https://www.wavosaur.com/)), or paying up to a few hundred dollars ([Sound Forge](https://www.magix.com/us/music-editing/sound-forge/), [Adobe Audition](https://www.adobe.com/products/audition.html)). Likewise, video-editing software can be free ([PiTiVi](https://www.pitivi.org/), [OpenShot](https://www.openshot.org/) for Linux, [iMovie](https://www.apple.com/imovie/) for Mac), less than $100 ([Adobe Premiere Elements](https://www.adobe.com/products/premiere-elements.html)), or several hundred dollars ([Adobe Premiere Pro](https://www.adobe.com/products/premiere.html), [Avid Media Composer](https://www.avid.com/media-composer), [Final Cut Pro](https://www.apple.com/final-cut-pro/)). The software you received with your digital camera may cover all your needs. +For audio files, you can find free software ([Audacity](https://www.audacityteam.org/), [Wavosaur](https://www.wavosaur.com/)), or paying up to a few hundred dollars ([Sound Forge](https://www.magix.com/us/music-editing/sound-forge/), [Adobe Audition](https://www.adobe.com/products/audition.html)). Likewise, video-editing software can be free ([PiTiVi](https://www.pitivi.org/), [OpenShot](https://www.openshot.org/) for Linux, [iMovie](https://support.apple.com/imovie) for Mac), less than $100 ([Adobe Premiere Elements](https://www.adobe.com/products/premiere-elements.html)), or several hundred dollars ([Adobe Premiere Pro](https://www.adobe.com/products/premiere.html), [Avid Media Composer](https://www.avid.com/media-composer), [Final Cut Pro](https://www.apple.com/final-cut-pro/)). The software you received with your digital camera may cover all your needs. ### Publishing tools diff --git a/files/en-us/learn/common_questions/tools_and_setup/set_up_a_local_testing_server/index.md b/files/en-us/learn/common_questions/tools_and_setup/set_up_a_local_testing_server/index.md index 2dcc6a5401ef704..df5e6c132cea28d 100644 --- a/files/en-us/learn/common_questions/tools_and_setup/set_up_a_local_testing_server/index.md +++ b/files/en-us/learn/common_questions/tools_and_setup/set_up_a_local_testing_server/index.md @@ -70,7 +70,7 @@ To use the module: npx -v ``` -2. If Node.js is not installed, you need to install it. Follow the [download instructions](https://nodejs.org/en/download/) in the Node.js docs, then run the above commands again to check if the installation is successful. +2. If Node.js is not installed, you need to install it. Follow the [download instructions](https://nodejs.org/en/download/package-manager) in the Node.js docs, then run the above commands again to check if the installation is successful. 3. Let's assume the directory is `/path/to/project`. Run the following command to start the server: @@ -85,30 +85,23 @@ To use the module: Another way to achieve this is to use Python's `http.server` module. > [!NOTE] -> Older versions of Python (up to version 2.7) provided a similar module named `SimpleHTTPServer`. If you are using Python 2.x, you can follow this guide by replacing all uses of `http.server` with `SimpleHTTPServer`. However, we recommend you use the latest version of Python. +> Older versions of Python (up to version 2.7) provided a similar module named `SimpleHTTPServer`. Python 2 is already end-of-life so we recommend using Python 3. To do this: -1. Install Python. If you are using Linux or macOS, it should be available on your system already. If you are a Windows user, you can get an installer from the Python homepage and follow the instructions to install it: - - - Go to [python.org](https://www.python.org/) - - Under the Download section, click the link for Python "3.xxx". - - At the bottom of the page, click the _Windows Installer_ link to download the installer file. - - When it has downloaded, run it. - - On the first installer page, make sure you check the "Add Python 3.xxx to PATH" checkbox. - - Click _Install_, then click _Close_ when the installation has finished. - -2. Open your command prompt (Windows) / terminal (macOS/ Linux). To check if Python is installed, enter the following command: +1. Run the following command to check if Python is already installed: ```bash python -V # If the above fails, try: python3 -V # Or, if the "py" command is available, try: - py -V + py -3 -V ``` -3. This should return a version number. If this is OK, navigate to the directory that contains the website code you want to test, using the `cd` command. +2. If Python is not installed, you need to install it. Follow the [download instructions](https://www.python.org/downloads/) in the Python docs (we also have more detailed explanations in our [Django tutorial](/en-US/docs/Learn/Server-side/Django/development_environment#installing_python_3)), then run the above commands again to check if the installation is successful. + +3. If Python is set up, navigate to the directory that contains the website code you want to test, using the `cd` command. ```bash # include the directory name to enter it, for example @@ -120,17 +113,14 @@ To do this: 4. Enter the command to start up the server in that directory: ```bash - # If Python version returned above is 3.X # On Windows, try "python -m http.server" or "py -3 -m http.server" python3 -m http.server - # If Python version returned above is 2.X - python -m SimpleHTTPServer ``` 5. By default, this will run the contents of the directory on a local web server, on port 8000. You can go to this server by going to the URL `localhost:8000` in your web browser. Here you'll see the contents of the directory listed — click the HTML file you want to run. > [!NOTE] -> If you already have something running on port 8000, you can choose another port by running the server command followed by an alternative port number, e.g. `python3 -m http.server 7800` (Python 3.x) or `python -m SimpleHTTPServer 7800` (Python 2.x). You can then access your content at `localhost:7800`. +> If you already have something running on port 8000, you can choose another port by running the server command followed by an alternative port number, e.g. `python3 -m http.server 7800`. You can then access your content at `localhost:7800`. ## Running server-side languages locally diff --git a/files/en-us/learn/common_questions/tools_and_setup/using_github_pages/index.md b/files/en-us/learn/common_questions/tools_and_setup/using_github_pages/index.md index 041f968268154f1..80cf23cb322cda6 100644 --- a/files/en-us/learn/common_questions/tools_and_setup/using_github_pages/index.md +++ b/files/en-us/learn/common_questions/tools_and_setup/using_github_pages/index.md @@ -15,7 +15,7 @@ GitHub is a very important and useful community to get involved in, and Git/GitH ### Basic GitHub setup 1. First of all, [install Git](https://git-scm.com/downloads) on your machine. This is the underlying version control system software that GitHub works on top of. -2. Next, [sign up for a GitHub account](https://github.com/join). It's simple and easy. +2. Next, [sign up for a GitHub account](https://github.com/signup). It's simple and easy. 3. Once you've signed up, log in to [github.com](https://github.com/) with your username and password. ### Preparing your code for upload diff --git a/files/en-us/learn/common_questions/tools_and_setup/what_are_browser_developer_tools/index.md b/files/en-us/learn/common_questions/tools_and_setup/what_are_browser_developer_tools/index.md index 011dd853076ad78..b797dc1c3c4030c 100644 --- a/files/en-us/learn/common_questions/tools_and_setup/what_are_browser_developer_tools/index.md +++ b/files/en-us/learn/common_questions/tools_and_setup/what_are_browser_developer_tools/index.md @@ -146,7 +146,7 @@ The final section, **Scopes**, shows what values are visible from various points Find out more about the JavaScript debugger in different browsers: - [Firefox JavaScript Debugger](https://firefox-source-docs.mozilla.org/devtools-user/debugger/index.html)) -- [Microsoft Edge Debugger](https://docs.microsoft.com/archive/microsoft-edge/legacy/developer/devtools-guide/debugger) +- [Microsoft Edge Debugger](https://learn.microsoft.com/en-us/archive/microsoft-edge/legacy/developer/devtools-guide/debugger) - [Chrome Debugger](https://developer.chrome.com/docs/devtools/javascript/) - [Safari Debugger](https://developer.apple.com/safari/tools/) diff --git a/files/en-us/learn/common_questions/tools_and_setup/what_software_do_i_need/index.md b/files/en-us/learn/common_questions/tools_and_setup/what_software_do_i_need/index.md index aba428d4983fd82..67912ad1ea97140 100644 --- a/files/en-us/learn/common_questions/tools_and_setup/what_software_do_i_need/index.md +++ b/files/en-us/learn/common_questions/tools_and_setup/what_software_do_i_need/index.md @@ -81,7 +81,7 @@ All desktop operating systems come with a basic text editor. These editors are a