centersl/mkdocs
1
0
Fork 0
mirror of https://github.com/mkdocs/mkdocs.git synced 2026-03-27 09:58:31 +07:00
Code Issues Packages Projects Releases Wiki Activity

Documentation improvements

Browse Source 
Clean up and improve the documentation following some recent changes.
Specificaly, ensure we consistantly document *two* required settings.
This commit is contained in:
Waylan Limberg
2021-05-18 10:19:49 -04:00
parent aae31c88c9
commit 5fc92b96e7
3 changed files with 50 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/about/release-notes.md
View File

@@ -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

13
docs/getting-started.md
View File

@@ -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

6
docs/user-guide/configuration.md
View File

@@ -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