docs: move codeblock title to props & use line highlight (#11991)

Author: Josh-Cena

docs/BypassingModuleMocks.md

@@ -7,8 +7,7 @@ Jest allows you to mock out whole modules in your tests, which can be useful for
 
 Consider writing a test case for this `createUser` function:
 
-```javascript
-// createUser.js
+```javascript title="createUser.js"
 import fetch from 'node-fetch';
 
 export const createUser = async () => {

docs/CodeTransformation.md

@@ -138,8 +138,7 @@ While `babel-jest` by default will transpile TypeScript files, Babel will not ve
 
 Importing images is a way to include them in your browser bundle, but they are not valid JavaScript. One way of handling it in Jest is to replace the imported value with its filename.
 
-```js
-// fileTransformer.js
+```js title="fileTransformer.js"
 const path = require('path');
 
 module.exports = {
@@ -149,9 +148,7 @@ module.exports = {
 };
 ```
 
-```js
-// jest.config.js
-
+```js title="jest.config.js"
 module.exports = {
   transform: {
     '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$':

docs/Configuration.md

@@ -16,8 +16,7 @@ Jest's configuration can be defined in the `package.json` file of your project,
 
 Or through JavaScript:
 
-```js
-// jest.config.js
+```js title="jest.config.js"
 // Sync object
 /** @type {import('@jest/types').Config.InitialOptions} */
 const config = {
@@ -36,8 +35,7 @@ module.exports = async () => {
 
 Or through TypeScript (if `ts-node` is installed):
 
-```ts
-// jest.config.ts
+```ts title="jest.config.ts"
 import type {Config} from '@jest/types';
 
 // Sync object
@@ -73,8 +71,7 @@ These options let you control Jest's behavior in your `package.json` file. The J
 
 You can retrieve Jest's default options to expand them if needed:
 
-```js
-// jest.config.js
+```js title="jest.config.js"
 const {defaults} = require('jest-config');
 module.exports = {
   // ...
@@ -99,8 +96,7 @@ This option tells Jest that all imported modules in your tests should be mocked
 
 Example:
 
-```js
-// utils.js
+```js title="utils.js"
 export default {
   authorize: () => {
     return 'token';
@@ -404,9 +400,7 @@ Test files are normally ignored from collecting code coverage. With this option,
 
 For example, if you have tests in source files named with `.t.js` extension as following:
 
-```javascript
-// sum.t.js
-
+```javascript title="sum.t.js"
 export function sum(a, b) {
   return a + b;
 }
@@ -464,17 +458,15 @@ _Note: While code transformation is applied to the linked setup-file, Jest will
 
 Example:
 
-```js
-// setup.js
+```js title="setup.js"
 module.exports = async () => {
   // ...
   // Set reference to mongod in order to close the server during teardown.
   global.__MONGOD__ = mongod;
 };
 ```
 
-```js
-// teardown.js
+```js title="teardown.js"
 module.exports = async function () {
   await global.__MONGOD__.stop();
 };
@@ -735,8 +727,7 @@ Custom reporter modules must define a class that takes a `GlobalConfig` and repo
 
 Example reporter:
 
-```js
-// my-custom-reporter.js
+```js title="my-custom-reporter.js"
 class MyCustomReporter {
   constructor(globalConfig, options) {
     this._globalConfig = globalConfig;
@@ -816,8 +807,7 @@ For example, if you want to respect Browserify's [`"browser"` field](https://git
 }
 ```
 
-```js
-// resolver.js
+```js title="resolver.js"
 const browserResolve = require('browser-resolve');
 
 module.exports = browserResolve.sync;
@@ -1303,8 +1293,7 @@ Example:
 
 Sort test path alphabetically.
 
-```js
-// testSequencer.js
+```js title="testSequencer.js"
 const Sequencer = require('@jest/test-sequencer').default;
 
 class CustomSequencer extends Sequencer {

docs/Es6ClassMocks.md

@@ -11,8 +11,7 @@ ES6 classes are constructor functions with some syntactic sugar. Therefore, any
 
 We'll use a contrived example of a class that plays sound files, `SoundPlayer`, and a consumer class which uses that class, `SoundPlayerConsumer`. We'll mock `SoundPlayer` in our tests for `SoundPlayerConsumer`.
 
-```javascript
-// sound-player.js
+```javascript title="sound-player.js"
 export default class SoundPlayer {
   constructor() {
     this.foo = 'bar';
@@ -24,8 +23,7 @@ export default class SoundPlayer {
 }
 ```
 
-```javascript
-// sound-player-consumer.js
+```javascript title="sound-player-consumer.js"
 import SoundPlayer from './sound-player';
 
 export default class SoundPlayerConsumer {
@@ -90,9 +88,7 @@ it('We can check if the consumer called a method on the class instance', () => {
 
 Create a [manual mock](ManualMocks.md) by saving a mock implementation in the `__mocks__` folder. This allows you to specify the implementation, and it can be used across test files.
 
-```javascript
-// __mocks__/sound-player.js
-
+```javascript title="__mocks__/sound-player.js"
 // Import this named export into your test file:
 export const mockPlaySoundFile = jest.fn();
 const mock = jest.fn().mockImplementation(() => {
@@ -104,8 +100,7 @@ export default mock;
 
 Import the mock and the mock method shared by all instances:
 
-```javascript
-// sound-player-consumer.test.js
+```javascript title="sound-player-consumer.test.js"
 import SoundPlayer, {mockPlaySoundFile} from './sound-player';
 import SoundPlayerConsumer from './sound-player-consumer';
 jest.mock('./sound-player'); // SoundPlayer is now a mock constructor
@@ -198,8 +193,7 @@ If you define an ES6 class using the same filename as the mocked class in the `_
 
 For the contrived example, the mock might look like this:
 
-```javascript
-// __mocks__/sound-player.js
+```javascript title="__mocks__/sound-player.js"
 export default class SoundPlayer {
   constructor() {
     console.log('Mock SoundPlayer: constructor was called');
@@ -297,9 +291,7 @@ jest.mock('./sound-player', () => {
 
 The manual mock equivalent of this would be:
 
-```javascript
-// __mocks__/sound-player.js
-
+```javascript title="__mocks__/sound-player.js"
 // Import this named export into your test file
 export const mockPlaySoundFile = jest.fn();
 const mock = jest.fn().mockImplementation(() => {
@@ -326,8 +318,7 @@ beforeEach(() => {
 
 Here's a complete test file which uses the module factory parameter to `jest.mock`:
 
-```javascript
-// sound-player-consumer.test.js
+```javascript title="sound-player-consumer.test.js"
 import SoundPlayer from './sound-player';
 import SoundPlayerConsumer from './sound-player-consumer';
 

docs/GettingStarted.md

@@ -89,8 +89,7 @@ yarn add --dev babel-jest @babel/core @babel/preset-env
 
 Configure Babel to target your current version of Node by creating a `babel.config.js` file in the root of your project:
 
-```javascript
-// babel.config.js
+```javascript title="babel.config.js"
 module.exports = {
   presets: [['@babel/preset-env', {targets: {node: 'current'}}]],
 };
@@ -102,8 +101,7 @@ _The ideal configuration for Babel will depend on your project._ See [Babel's do
 
 Jest will set `process.env.NODE_ENV` to `'test'` if it's not set to something else. You can use that in your configuration to conditionally setup only the compilation needed for Jest, e.g.
 
-```javascript
-// babel.config.js
+```javascript title="babel.config.js"
 module.exports = api => {
   const isTest = api.env('test');
   // You can use isTest to determine what presets and plugins to use.
@@ -116,8 +114,7 @@ module.exports = api => {
 
 > Note: `babel-jest` is automatically installed when installing Jest and will automatically transform files if a babel configuration exists in your project. To avoid this behavior, you can explicitly reset the `transform` configuration option:
 
-```javascript
-// jest.config.js
+```javascript title="jest.config.js"
 module.exports = {
   transform: {},
 };
@@ -160,12 +157,12 @@ yarn add --dev @babel/preset-typescript
 
 Then add `@babel/preset-typescript` to the list of presets in your `babel.config.js`.
 
-```diff
-// babel.config.js
+```javascript title="babel.config.js"
 module.exports = {
   presets: [
     ['@babel/preset-env', {targets: {node: 'current'}}],
-+    '@babel/preset-typescript',
+    // highlight-next-line
+    '@babel/preset-typescript',
   ],
 };
 ```

docs/JestObjectAPI.md

@@ -25,17 +25,15 @@ Jest configuration:
 
 Example:
 
-```js
-// utils.js
+```js title="utils.js"
 export default {
   authorize: () => {
     return 'token';
   },
 };
 ```
 
-```js
-// __tests__/disableAutomocking.js
+```js title="__tests__/disableAutomocking.js"
 import utils from '../utils';
 
 jest.disableAutomock();
@@ -65,8 +63,7 @@ Returns the `jest` object for chaining.
 
 Example:
 
-```js
-// utils.js
+```js title="utils.js"
 export default {
   authorize: () => {
     return 'token';
@@ -75,8 +72,7 @@ export default {
 };
 ```
 
-```js
-// __tests__/enableAutomocking.js
+```js title="__tests__/enableAutomocking.js"
 jest.enableAutomock();
 
 import utils from '../utils';
@@ -102,8 +98,7 @@ This is useful when you want to create a [manual mock](ManualMocks.md) that exte
 
 Example:
 
-```js
-// utils.js
+```js title="utils.js"
 export default {
   authorize: () => {
     return 'token';
@@ -112,8 +107,7 @@ export default {
 };
 ```
 
-```js
-// __tests__/createMockFromModule.test.js
+```js title="__tests__/createMockFromModule.test.js"
 const utils = jest.createMockFromModule('../utils').default;
 utils.isAuthorized = jest.fn(secret => secret === 'not wizard');
 
@@ -147,8 +141,7 @@ Creates a new property with the same primitive value as the original property.
 
 Example:
 
-```js
-// example.js
+```js title="example.js"
 module.exports = {
   function: function square(a, b) {
     return a * b;
@@ -178,8 +171,7 @@ module.exports = {
 };
 ```
 
-```js
-// __tests__/example.test.js
+```js title="__tests__/example.test.js"
 const example = jest.createMockFromModule('./example');
 
 test('should run example code', () => {
@@ -220,11 +212,11 @@ test('should run example code', () => {
 
 Mocks a module with an auto-mocked version when it is being required. `factory` and `options` are optional. For example:
 
-```js
-// banana.js
+```js title="banana.js"
 module.exports = () => 'banana';
+```
 
-// __tests__/test.js
+```js title="__tests__/test.js"
 jest.mock('../banana');
 
 const banana = require('../banana'); // banana will be explicitly mocked.

docs/JestPlatform.md

@@ -123,19 +123,15 @@ Module used for parallelization of tasks. Exports a class `JestWorker` that take
 
 ### Example
 
-```javascript
-// heavy-task.js
-
+```javascript title="heavy-task.js"
 module.exports = {
   myHeavyTask: args => {
     // long running CPU intensive task.
   },
 };
 ```
 
-```javascript
-// main.js
-
+```javascript title="main.js"
 async function main() {
   const worker = new Worker(require.resolve('./heavy-task.js'));
 

docs/ManualMocks.md

@@ -40,8 +40,7 @@ When a manual mock exists for a given module, Jest's module system will use that
 
 Here's a contrived example where we have a module that provides a summary of all the files in a given directory. In this case, we use the core (built in) `fs` module.
 
-```javascript
-// FileSummarizer.js
+```javascript title="FileSummarizer.js"
 'use strict';
 
 const fs = require('fs');
@@ -58,8 +57,7 @@ exports.summarizeFilesInDirectorySync = summarizeFilesInDirectorySync;
 
 Since we'd like our tests to avoid actually hitting the disk (that's pretty slow and fragile), we create a manual mock for the `fs` module by extending an automatic mock. Our manual mock will implement custom versions of the `fs` APIs that we can build on for our tests:
 
-```javascript
-// __mocks__/fs.js
+```javascript title="__mocks__/fs.js"
 'use strict';
 
 const path = require('path');
@@ -96,8 +94,7 @@ module.exports = fs;
 
 Now we write our test. Note that we need to explicitly tell that we want to mock the `fs` module because it’s a core Node module:
 
-```javascript
-// __tests__/FileSummarizer-test.js
+```javascript title="__tests__/FileSummarizer-test.js"
 'use strict';
 
 jest.mock('fs');