Update guides/hack from HHVM repository

Wilfred · github-actions[bot] · commit a58af98f5393 · 2025-10-30T15:22:45.000Z
diff --git a/guides/hack/15-asynchronous-operations/07-awaitables.md b/guides/hack/15-asynchronous-operations/07-awaitables.md
@@ -1,11 +1,5 @@
 # Awaitables
 
-<!-- ```yamlmeta
-{
-  "namespace": "HH\\Asio"
-}
-``` -->
-
 An *awaitable* is the key construct in `async` code. An awaitable is a first-class object that represents a possibly asynchronous
 operation that may or may not have completed. We `await` the awaitable until the operation has completed.
 
diff --git a/guides/hack/90-contributing/01-introduction.md b/guides/hack/90-contributing/01-introduction.md
@@ -1,99 +1,35 @@
 # Introduction
 
-:::caution
-
-The below instructions are out of date. The documentation site is now moved over to [Docusaurus](https://docusaurus.io/).
-
-:::
-
 ## Prerequisites
 
-You'll need HHVM
-(see [installation instructions](/docs/hhvm/installation/introduction))
-installed on your local machine, and the version must have the same major
-and minor (e.g. `4.123`) as the version specification in the `composer.json`
-file.
-
-You'll also need a checkout of the source code for this site.
-
-```
-$ git clone git@github.com:hhvm/user-documentation.git
-```
-
-## Composer Dependencies
-
-We use Composer to manage our PHP library dependencies and to autoload classes.
-Composer is written in PHP, so you need PHP installed.
-
-```
-# Ubuntu example, your environment may differ.
-$ apt-get install php-cli
-```
-
-You can now follow the instructions on [the Composer website](https://getcomposer.org/) to install it.
-
-Once you've installed `composer.phar`, you can install the website dependencies into `vendor/` and create the autoload map.
-
-```
-$ cd user-documentation
-user-documentation$ php /path/to/composer.phar install
-```
+This documentation site is built with [Docusaurus](https://docusaurus.io/). To run the site locally for development and testing, ensure [Node.js](https://nodejs.org/en/) (v20.0 or above) and [Yarn](https://yarnpkg.com/) are installed.
 
-### Updating Dependencies
+<FbInfo>
+As a Meta employee, to run the site on an **On Demand** or a **Dev Server**, follow the instructions on the [Static Docs prerequisites page](https://www.internalfb.com/intern/staticdocs/staticdocs/docs/setup/2-prequisites/), which also describes how to set up proxying. Any updates to the documentation in the repository will be reflected on the [internal Static Docs](https://www.internalfb.com/intern/staticdocs/hack/) site through [automated periodic deployments](https://www.internalfb.com/intern/staticdocs/staticdocs/docs/setup/4-configerator/#periodic-deployment)
+</FbInfo>
 
-We require that this whole repository has no type errors.
+## Running locally
 
-```
-$ hh_client
-No errors!
-```
+1. Navigate to the `website/` directory and run `yarn install` to install all the required dependencies.
 
-If you are seeing errors in `vendor/`, re-run the composer install command to ensure that all dependencies are up to date.
+2. Next, to run the site locally, run `yarn start`.
 
-**NOTE**: If you add, delete or rename a class in the primary source tree `src/`, you should run `php composer.phar dump-autoload` in order to make the autoload maps refresh correctly; otherwise you will get class not found exceptions.
+3. This will start a local server on port 3000. You can view the site at [http://localhost:3000](http://localhost:3000).
 
-## Running A Local Instance
+<FbInfo>
+The documentation site allows for creation of internal paragraphs/blocks that are only visible to Meta employees. To view these parts of the documentation, you must be on a Meta network or VPN. For local testing, running `yarn start-fb` will switch the local server into a mode that will allow you to view the internal-only parts of the documentation.
+</FbInfo>
 
-Generate `public/` by running the build script. This script will only
-run the steps related to your changes, so the first run will be slower
-than later runs.
+Whilst `yarn start` is running, any changes made to the documentation will be published to the local instance automatically, allowing for a fast feedback loop as you make updates.
 
-```
-$ hhvm bin/build.php
-```
+## Running an old version
 
-HHVM has a built-in webserver, so it can serve the entire website.
-
-```
-$ cd public
-$ hhvm -m server -p 8080 -c ../hhvm.dev.ini
-```
-
-You can now see your local instance by visiting [http://localhost:8080](http://localhost:8080).
-
-When you make changes, you'll need to run `build.php` again. You can
-leave HHVM serving the site, and it will pick up the changes
-automatically.
-
-## Running An Old Instance
-
-If you want to see old versions of the docs, we provide [regular Docker
-images of this site](https://ghcr.io/hhvm/user-documentation) (previously
+If you want to see old versions of the docs (from before our migration to Docusaurus in 2025), we provided [regular Docker images of the old documentation site](https://ghcr.io/hhvm/user-documentation) on GHCR (previously
 on [Docker Hub](https://hub.docker.com/r/hhvm/user-documentation/tags)).
-This is not suitable for development, but is useful if you're working with
-an old HHVM/Hack version.
-
 
+These images are not suitable for development, but are useful if you are working with
+an old HHVM/Hack version.
 
 1. Install [Docker](https://docs.docker.com/engine/installation/).
 2. Start a container with: `docker run -p 8080:80 -d ghcr.io/hhvm/user-documentation`.
 3. You can then access a local copy of the documentation at [http://localhost:8080](http://localhost:8080).
-
-## Running A Production Instance
-
-Running a production instance is very similar to a development
-instance.
-
-Configure a webserver and HHVM to serve the `public/`
-directory. Ensure that all requests that don't match a local file are
-served by `index.php`.
diff --git a/guides/hack/90-contributing/06-writing-content.md b/guides/hack/90-contributing/06-writing-content.md
@@ -13,7 +13,11 @@ The website has three content sections:
   examples](https://github.com/hhvm/user-documentation/tree/main/api-examples)
   for each API
 
-## File Naming Conventions
+<FbInfo>
+Internally, the sources for all of the Hack, HHVM, HSL and API guides are stored under the same directory, `fbcode/hphp/hack/manual/`. The Hack guides are set up to automatically mirror those on `hhvm/user-documentation`
+</FbInfo>
+
+## File naming conventions
 
 A guide is a folder with a numeric prefix:
 
@@ -26,59 +30,47 @@ $ ls guides/hack/
 
 These numbers are used to control the ordering of guides on the
 website, and are not shown in the UI. They do not need to be
-sequential: there can be gaps.
+sequential; there can be gaps.
 
-Within each folder, there are markdown files (written in [GitHub
-flavored markdown](https://github.github.com/gfm/)), a `foo-category.txt` (used
-for grouping on the home page) and a `foo-summary.txt` (shown as a subheading on
-the home page).
+Within each folder, there are Markdown files (written in [Markdown](https://docusaurus.io/docs/markdown-features)).
 
 ```
-$ ls guides/hack/getting-started/
-01-getting-started.md
+$ ls guides/hack/01-getting-started/
+01-quick-start.md
 02-tools.md
-getting-started-category.txt
-getting-started-summary.txt
 ```
 
 Pages use the same numbering system to control their order within a
 guide.
 
-## Writing Conventions
+## Writing conventions
 
 Guides are written in a relatively informal tone, addressing the
 reader as "you". Assume the reader has some programming knowledge but
 no familiarity with Hack.
 
 Each page should have a clear purpose, starting with a short
-description of the concept it's describing. Examples should always be
+description of the concept it is describing. Examples should always be
 provided, preferably under 15 lines.
 
 We assume the reader has a relatively recent version of
 HHVM. References to very old features will be removed, but we provide
 [Docker images of historical site
-versions](/docs/hack/contributing/introduction#running-an-old-instance) if
-needed.
+versions](/docs/hack/contributing/introduction#running-an-old-version) if
+needed (from before we migrated to Docusaurus in 2025).
 
-It's not necessary to document all the incorrect ways a feature can be
+It is not necessary to document all the incorrect ways a feature can be
 used. Content should focus on correct usage, and users can rely on the
-Hack type checker to tell them when they've done something wrong.
+Hack type checker to tell them when they have done something wrong.
 
 ## Links
 
-Internal links should be absolute paths without a domain,
+Internal links should be **absolute paths** without a domain,
 e.g. `/hack/contributing/introduction`.
 
-Image paths should be relative to `public`,
-e.g. `/images/imagename.png`.
-
-When removing or renaming pages, set up a redirect from the old
-URL. See [`Guides::getGuidePageRedirects`](https://github.com/hhvm/user-documentation/blob/9fd2aaeb60a236072ef99735a9114ec54d96da2c/src/Guides.php#L56).
-
-## Styling
+Image paths should be relative to `static`,
+e.g. `/img/imagename.png`.
 
-We use [Sass](https://sass-lang.com/) to style the website, and the
-source files are in
-[sass/](https://github.com/hhvm/user-documentation/tree/main/sass).
+### Validating links
 
-The CSS files are generated by the build script.
+To make sure all links between pages are valid, run `yarn docusaurus build`. This will check all links in the documentation and report any broken ones. It is generally advised to run this command before submitting a diff to ensure that all links are valid and that the changes do not break upstream publishing pipelines.
diff --git a/guides/hack/90-contributing/10-code-samples.md b/guides/hack/90-contributing/10-code-samples.md
@@ -1,8 +1,22 @@
 # Code Samples
 
-All code samples are automatically type checked and executed, to ensure they're correct.
+All code samples are automatically type checked and executed, to ensure they are correct.
 
-## Basic Usage
+<FbInfo>
+
+When working in `fbsource`, you can trigger this manually and check the results before submitting a diff (see more details on [the internal wiki](https://www.internalfb.com/wiki/Hack_Developer_Guide/Contributing_to_HHVM_Documentation/)):
+
+```bash
+# Or wherever you have fbsource checked out
+$ cd ~/fbsource/fbcode
+$ buck2 run //hphp/hack/src/hh_manual:hh_manual extract hphp/hack/manual/hack/
+$ buck2 test //hphp/hack/test/typecheck:extracted_from_manual
+$ buck2 test //hphp/hack/test/typecheck:extracted_from_manual_error
+```
+
+</FbInfo>
+
+## Basic usage
 
 Code samples require triple backticks, and a file name.
 
@@ -29,7 +43,7 @@ echo "Hello world!\n";
 ```
 ~~~
 
-## Opting Out
+## Opting out
 
 If you really need to write a code sample that isn't checked or executed, you can omit the file name. The code sample will be included in the docs without any checking.
 
@@ -40,7 +54,16 @@ If you really need to write a code sample that isn't checked or executed, you ca
 ```
 ~~~
 
-## Sharing Code
+To maintain syntax highlighting, you want to retain the language specifier.
+In those cases, you can also opt-out of extraction entirely using the `no-extract` specifier. E.g., the below example will be shown on the website with Hack syntax highlighting, but the type checker will ignore it when the validation job is run.
+
+~~~
+```hack no-extract
+I am in the manual, but not checked.
+```
+~~~
+
+## Sharing code
 
 By default, each extracted example file has its own namespace based on the file name. This allows multiple examples to define the same class or function.
 
@@ -115,7 +138,7 @@ This can also be more convenient because we can rely on the automatic
 boilerplate addition by the build script, instead of manually writing the
 `<<__EntryPoint>>` function header.
 
-## Examples with Hack Errors
+## Examples with Hack errors
 
 Examples that are expected to fail typechecking should use the `.type-errors`
 extension:
@@ -129,7 +152,7 @@ function missing_return_type() {}
 The build script will run the Hack typechecker and include its output in the
 rendered HTML (instead of HHVM runtime output).
 
-## Supporting Files
+## Supporting files
 
 An example code block may specify additional files to be extracted alongside the
 example code using the following format:
@@ -145,7 +168,7 @@ Your lucky number is: %d
 ~~~
 
 Supported extensions are inherited from the
-[HHVM test runner](https://github.com/facebook/hhvm/blob/master/hphp/test/README#file-layout):
+[HHVM test runner](https://github.com/facebook/hhvm/blob/master/hphp/test/README.md#file-layout):
 
 - `.hhconfig` if the example requires specific *typechecker* flags
   (e.g. demonstrating a feature that is not yet enabled by default)
@@ -168,7 +191,7 @@ Supported extensions are inherited from the
   MySQL server running), otherwise print nothing
 
 
-## Testing Changes
+## Testing changes
 
 We have a test suite to ensure consistency across the changes we make to the guides, API references, and examples.
 
@@ -178,7 +201,7 @@ You can run it as follows:
 $ vendor/bin/hacktest tests/
 ```
 
-## Running the Examples
+## Running the examples
 
 Nearly all of the code examples you see in the guides and API documentation are actual Hack or PHP source files that are embedded at site build time into the content itself.
 
@@ -239,7 +262,7 @@ object(HH\Vector)#10 (5) {
 Time non lazy: 0.0096559524536133
 ```
 
-### Using the HHVM Test Runner
+### Using the HHVM test runner
 
 Each example is structured to be run with the [HHVM test runner](https://github.com/facebook/hhvm/blob/master/hphp/test/README). We use the test runner internally to ensure that any changes made to HHVM do not cause a regression. The examples in the documentation here can be used for that purpose as well.
 
diff --git a/guides/hack/90-contributing/12-information-macros.md b/guides/hack/90-contributing/12-information-macros.md
@@ -1,46 +1,42 @@
 # Information Macros
 
-This website supports note, tip, caution, and danger macro messages.
-
-## Note Message
-```yamlmeta
-{
-  "note": [
-    "This change was introduced in [HHVM 4.136](https://hhvm.com/blog/2021/11/19/hhvm-4.136.html)."
-  ]
-}
+This website supports `note`, `tip`, `caution`, and `danger` macro messages.
+
+These can be added with [admonition](https://docusaurus.io/docs/markdown-features/admonitions) syntax:
+
+```markdown
+:::note
+Your **content** goes here...
+:::
 ```
 
+## Note message
+
+:::note
+This change was introduced in [HHVM 4.136](https://hhvm.com/blog/2021/11/19/hhvm-4.136.html).
+:::
+
 The `noreturn` type can be upcasted to `dynamic`.
 
-## Tip Message
-```yamlmeta
-{
-  "tip": [
-    "To start learning Hack, read our [Getting Started](/docs/hack/getting-started/getting-started) documentation!"
-  ]
-}
-```
+## Tip message
+
+:::tip
+To start learning Hack, read our [Getting Started](/docs/hack/getting-started/quick-start) documentation!
+:::
+
 Hack lets you write code quickly, while also having safety features built in, like static type checking.
 
-## Caution Message
-```yamlmeta
-{
-  "caution": [
-    "We do not recommend using experimental features until they are formally announced and integrated into the main documentation set."
-  ]
-}
-```
+## Caution message
+
+:::caution
+We do not recommend using experimental features until they are formally announced and integrated.
+:::
 
 This website maintains documentation on Hack features that are in the *experimental* phase.
 
-## Warning Message
-```yamlmeta
-{
-  "danger": [
-    "Use this method with caution. **If your query contains *ANY* unescaped input, you are putting your database at risk.**"
-  ]
-}
-```
+## Warning message
+:::danger
+Use this method with caution. **If your query contains *ANY* unescaped input, you are putting your database at risk.**
+:::
 
 While inherently dangerous, you can use `AsyncMysqlConnection::query` to query a MySQL database client.
