fix(create-docusaurus): improve init template misleading doc + add Docuaurus social card (#8279)

packages/create-docusaurus/templates/classic/docusaurus.config.js

@@ -8,17 +8,22 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 const config = {
   title: 'My Site',
   tagline: 'Dinosaurs are cool',
-  url: 'https://your-docusaurus-test-site.com',
-  baseUrl: '/',
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
   favicon: 'img/favicon.ico',
 
+  // Set the production url of your site here
+  url: 'https://your-docusaurus-test-site.com',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/',
+
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: 'facebook', // Usually your GitHub org/user name.
   projectName: 'docusaurus', // Usually your repo name.
 
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
   // Even if you don't use internalization, you can use this field to set useful
   // metadata like html lang. For example, if your site is Chinese, you may want
   // to replace "en" with "zh-Hans".
@@ -56,6 +61,8 @@ const config = {
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
+      // Replace with your project's social card
+      image: 'img/docusaurus-social-card.jpg',
       navbar: {
         title: 'My Site',
         logo: {

packages/create-docusaurus/templates/facebook/docusaurus.config.js

@@ -13,17 +13,22 @@
 const config = {
   title: 'My Site',
   tagline: 'The tagline of my site',
-  url: 'https://your-docusaurus-test-site.com',
-  baseUrl: '/',
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
   favicon: 'img/favicon.ico',
 
+  // Set the production url of your site here
+  url: 'https://your-docusaurus-test-site.com',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/',
+
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: 'facebook', // Usually your GitHub org/user name.
   projectName: 'docusaurus', // Usually your repo name.
 
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
   presets: [
     [
       'classic',
@@ -53,6 +58,7 @@ const config = {
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
+      image: 'img/docusaurus-social-card.jpg',
       navbar: {
         title: 'My Meta Project',
         logo: {

packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx

@@ -51,7 +51,11 @@ You can use absolute paths to reference images in the static directory (`static/
 
 ![Docusaurus logo](/img/docusaurus.png)
 
-You can reference images relative to the current file as well, as shown in [the extra guides](../tutorial-extras/manage-docs-versions.md).
+You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
+
+```md
+![Docusaurus logo](./img/docusaurus.png)
+```
 
 ## Code Blocks
 

packages/docusaurus-theme-classic/src/__tests__/options.test.ts

@@ -62,7 +62,7 @@ describe('themeConfig', () => {
         textColor: '#000',
         isCloseable: true,
       },
-      image: 'img/docusaurus-soc.png',
+      image: 'img/docusaurus-social-card.jpg',
       navbar: {
         style: 'primary',
         hideOnScroll: true,

website/docusaurus.config-blog-only.js

@@ -41,7 +41,7 @@ module.exports = {
     ],
   ],
   themeConfig: {
-    image: 'img/docusaurus-soc.png',
+    image: 'img/docusaurus-social-card.jpg',
     algolia: {
       appId: 'X1Z85QJPUV',
       apiKey: 'bf7211c161e8205da2f933a02534105a',

website/docusaurus.config.js

@@ -403,7 +403,7 @@ const config = {
           },
         ],
       },
-      image: 'img/docusaurus-soc.png',
+      image: 'img/docusaurus-social-card.jpg',
       // metadata: [{name: 'twitter:card', content: 'summary'}],
       algolia: {
         appId: 'X1Z85QJPUV',