diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index d89c60b0..73164d0b 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -70,7 +70,7 @@ in the Configuration documentation for details. #### Update `gh-deploy` command (#2170) The vendored (and modified) copy of ghp_import has been replaced with a -dependency on the upstream library. As of version 1.0.0, [ghp_import] includes a +dependency on the upstream library. As of version 1.0.0, [ghp-import] includes a Python API which makes it possible to call directly. MkDocs can now benefit from recent bug fixes and new features, including the following: @@ -120,46 +120,46 @@ configuration documentation for details. ### Backward Incompatible Changes in 1.2 -The [site_url](../user-guide/configuration.md#site_url) configuration option is -now **required**. If it is not set, a warning will be issued. In a future -release an error will be raised (#2189). +* The [site_url](../user-guide/configuration.md#site_url) configuration option + is now **required**. If it is not set, a warning will be issued. In a future + release an error will be raised (#2189). -The [use_directory_urls](../user-guide/configuration.md#use_directory_urls) -configuration option will be forced to `false` if -[site_url](../user-guide/configuration.md#site_url) is set to an emtpy string. -If `use_directory_urls` is not explicitly set to `false` a warning will be -issued (#2189). + The [use_directory_urls](../user-guide/configuration.md#use_directory_urls) + configuration option will be forced to `false` if + [site_url](../user-guide/configuration.md#site_url) is set to an emtpy + string. In that case, if `use_directory_urls` is not explicitly set to + `false`, a warning will be issued (#2189). -A theme's files are now excluded from the list of watched files by default -when using the `--livereload` server. This new default behavior is what most -users need and provides better performance when editing site content. -Theme developers can enable the old behavior with the `--watch-theme` -option. (#2092). +* A theme's files are now excluded from the list of watched files by default + when using the `--livereload` server. This new default behavior is what most + users need and provides better performance when editing site content. + Theme developers can enable the old behavior with the `--watch-theme` + option. (#2092). -The `mkdocs` theme now removes the sidebar when printing a page. This frees -up horizontal space for better rendering of content like tables (#2193). +* The `mkdocs` theme now removes the sidebar when printing a page. This frees + up horizontal space for better rendering of content like tables (#2193). -The `mkdocs.config.DEFAULT_SCHEMA` global variable has been replaced with the -function `mkdocs.config.defaults.get_schema()`, which ensures that each -instance of the configuration is unique (#2289). +* The `mkdocs.config.DEFAULT_SCHEMA` global variable has been replaced with the + function `mkdocs.config.defaults.get_schema()`, which ensures that each + instance of the configuration is unique (#2289). -The `mkdocs.utils.warning_filter` is deprecated and now does nothing. Plugins - should remove any reference to is as it may be deleted in a future release. - To ensure any warnings get counted, simply log them to the `mkdocs` log (i.e: -`mkdocs.plugins.pluginname`). +* The `mkdocs.utils.warning_filter` is deprecated and now does nothing. Plugins + should remove any reference to is as it may be deleted in a future release. + To ensure any warnings get counted, simply log them to the `mkdocs` log (i.e: + `mkdocs.plugins.pluginname`). -The `python` method of the `plugins.search.prebuild_index` configuration option -is pending deprecation as of version 1.2. It is expected that in version 1.3 it -will raise a warning if used and in version 1.4 it will raise an error. Users -are encouraged to use an alternate method to generate a prebuilt index for -search. +* The `python` method of the `plugins.search.prebuild_index` configuration + option is pending deprecation as of version 1.2. It is expected that in + version 1.3 it will raise a warning if used and in version 1.4 it will raise + an error. Users are encouraged to use an alternate method to generate a + prebuilt index for search. -The `lunr` and `lunr[languages]` dependencies are no longer installed by -default. The dependencies are only needed for the rare user who prebuilds the -search index and uses the `python` option, which is now pending deprecation. If -you use this feature, then you will need to manually install `lunr` and -`lunr[languages]`. A warning is issued if the dependencies are needed but not -installed. +* The `lunr` and `lunr[languages]` dependencies are no longer installed by + default. The dependencies are only needed for the rare user who prebuilds the + search index and uses the `python` option, which is now pending deprecation. + If you use this feature, then you will need to manually install `lunr` and + `lunr[languages]`. A warning is issued if the dependencies are needed but not + installed. ### Other Changes and Additions to Version 1.2 diff --git a/docs/getting-started.md b/docs/getting-started.md index 8e680e66..cbcd0b53 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -65,6 +65,7 @@ Now try editing the configuration file: `mkdocs.yml`. Change the ```yaml site_name: MkLorum +site_url: https://example.com/ ``` Your browser should immediately reload, and you'll see your new site name take @@ -72,6 +73,15 @@ effect. ![The site_name setting](img/site-name.png) +!!! note + + The [`site_name`][site_name] and [`site_url`][site_url] configuration + options are the only two required options in your configuration file. When + you create a new project, the `site_url` option is assigned the placeholder + value: `https://example.com`. If the final location is known, you can change + the setting now to point to it. Or you may choose to leave it alone for now. + Just be sure to edit it before you deploy your site to a production server. + ## Adding pages Now add a second page to your documentation: @@ -87,6 +97,7 @@ setting: ```yaml site_name: MkLorum +site_url: https://example.com/ nav: - Home: index.md - About: about.md @@ -114,6 +125,7 @@ changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] settin ```yaml site_name: MkLorum +site_url: https://example.com/ nav: - Home: index.md - About: about.md @@ -205,5 +217,6 @@ To get help with MkDocs, please use the [GitHub discussions] or [GitHub issues]. [GitHub discussions]: https://github.com/mkdocs/mkdocs/discussions [GitHub issues]: https://github.com/mkdocs/mkdocs/issues [site_name]: user-guide/configuration.md#site_name +[site_url]: user-guide/configuration.md#site_url [theme]: user-guide/configuration.md#theme [User Guide]: user-guide/index.md diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 358f4d35..23b71df4 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -9,8 +9,8 @@ Guide to all available configuration settings. Project settings are always configured by using a YAML configuration file in the project directory named `mkdocs.yml`. -As a minimum, this configuration file must contain the `site_name` setting. All -other settings are optional. +As a minimum, this configuration file must contain the `site_name` and +`site_url` settings. All other settings are optional. ### Environment Variables @@ -73,7 +73,7 @@ need to be updated prior to deployment. If the built site will not be behind a server, then you may set the value to an empty string (`''`). When set to an empty string, some features of MkDocs may -act differently. For example, the [use_directory_urls](#use_direcotry_urls) +act differently. For example, the [use_directory_urls](#use_directory_urls) setting must be set to `false`. ### repo_url