Merge pull request #27 from ProperDocs/yml

Read the config from properdocs.yml and fall back to mkdocs.yml

Author: oprypin

CONTRIBUTING.md

@@ -25,7 +25,7 @@ It is particularly helpful if an issue report touches on all of these aspects:
 
 1.  What are you trying to achieve?
 
-2.  What is your `mkdocs.yml` configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example.
+2.  What is your `properdocs.yml` configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example.
 
 3.  What did you expect to happen when applying this setup?
 
@@ -119,7 +119,7 @@ Documentation files are also checked by markdownlint, so you should run this as
 hatch run lint:check
 ```
 
-If you add a new plugin to mkdocs.yml, you don't need to add it to any "requirements" file, because that is managed automatically.
+If you add a new plugin to properdocs.yml, you don't need to add it to any "requirements" file, because that is managed automatically.
 
 > INFO: If you don't want to use Hatch, for documentation you can install requirements into a virtualenv, in one of these ways (with `.venv` being the virtualenv directory):
 >

docs/about/release-notes.md

@@ -102,7 +102,7 @@ See `color_mode`, `user_color_mode_toggle` in [**documentation**](../user-guide/
 
 > WARNING: **Possible breaking change.**
 >
-> jQuery is no longer included into the "mkdocs" theme. If you were relying on it in your scripts, you will need to separately add it first (into mkdocs.yml) as an extra script:
+> jQuery is no longer included into the "mkdocs" theme. If you were relying on it in your scripts, you will need to separately add it first (into `properdocs.yml`) as an extra script:
 >
 > ```yaml
 > extra_javascript:
@@ -328,11 +328,11 @@ pip install $(mkdocs get-deps)
 
 The idea is that right after running this command, you can directly follow it up with `mkdocs build` and it will almost always "just work", without needing to think which dependencies to install.
 
-The way it works is by scanning `mkdocs.yml` for `themes:`, `plugins:`, `markdown_extensions:` items and doing a reverse lookup based on a large list of known projects (catalog, see below).
+The way it works is by scanning `properdocs.yml` for `themes:`, `plugins:`, `markdown_extensions:` items and doing a reverse lookup based on a large list of known projects (catalog, see below).
 
 Of course, you're welcome to use a "virtualenv" with such a command. Also note that for environments that require stability (for example CI) directly installing deps in this way is not a very reliable approach as it precludes dependency pinning.
 
-The command allows overriding which config file is used (instead of `mkdocs.yml` in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See [`mkdocs get-deps --help`](../user-guide/cli.md#properdocs-get-deps).
+The command allows overriding which config file is used (instead of `properdocs.yml` in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See [`mkdocs get-deps --help`](../user-guide/cli.md#properdocs-get-deps).
 
 Context: #3205
 
@@ -356,7 +356,7 @@ Now, in addition to validating relative links, MkDocs will print `INFO` messages
 INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'?
 ```
 
-If you don't want any changes, not even the `INFO` messages, and wish to revert to the silence from MkDocs 1.4, add the following configs to `mkdocs.yml` (**not** recommended):
+If you don't want any changes, not even the `INFO` messages, and wish to revert to the silence from MkDocs 1.4, add the following configs to `properdocs.yml` (**not** recommended):
 
 ```yaml
 validation:

docs/dev-guide/plugins.md

@@ -130,7 +130,7 @@ class MyPlugin(properdocs.plugins.BasePlugin):
 >
 > ```yaml
 > my_plugin:
->   definition_file: configs/test.ini  # relative to mkdocs.yml
+>   definition_file: configs/test.ini  # relative to properdocs.yml
 >   validation:
 >     enabled: !ENV [CI, false]
 >     verbose: true

docs/dev-guide/themes.md

@@ -23,13 +23,13 @@ the code to describe the different features and their usage.
 
 The bare minimum required for a custom theme is a `main.html` [Jinja2
 template] file which is placed in a directory that is *not* a child of the
-[docs_dir]. Within `mkdocs.yml`, set the [`theme.custom_dir`][custom_dir]
+[docs_dir]. Within `properdocs.yml`, set the [`theme.custom_dir`][custom_dir]
 option to the path of the directory containing `main.html`. The path should be
 relative to the configuration file. For example, given this example project
 layout:
 
 ```text
-mkdocs.yml
+properdocs.yml
 docs/
     index.md
     about.md
@@ -38,7 +38,7 @@ custom_theme/
     ...
 ```
 
-... you would include the following settings in `mkdocs.yml` to use the custom theme
+... you would include the following settings in `properdocs.yml` to use the custom theme
 directory:
 
 ```yaml
@@ -64,7 +64,7 @@ theme:
 > A theme's [configuration] defined in a `mkdocs_theme.yml` file is not loaded
 > from `theme.custom_dir`. When an entire theme exists in `theme.custom_dir`
 > and `theme.name` is set to `null`, then the entire theme configuration must
-> be defined in the [theme] configuration option in the `mkdocs.yml` file.
+> be defined in the [theme] configuration option in the `properdocs.yml` file.
 >
 > However, when a theme is [packaged] up for distribution, and loaded using
 > the `theme.name` configuration option, then a `mkdocs_theme.yml` file
@@ -101,7 +101,7 @@ The simplest `main.html` file is the following:
 </html>
 ```
 
-The body content from each page specified in `mkdocs.yml` is inserted using the
+The body content from each page specified in `properdocs.yml` is inserted using the
 `{{ page.content }}` tag. Style-sheets and scripts can be brought into this
 theme as with a normal HTML file. Navbars and tables of contents can also be
 generated and included automatically, through the `nav` and `toc` objects,
@@ -232,7 +232,7 @@ The following variables are available globally on any template.
 #### config
 
 The `config` variable is an instance of ProperDocs' config object generated from the
-`mkdocs.yml` config file. While you can use any config option, some commonly
+`properdocs.yml` config file. While you can use any config option, some commonly
 used options include:
 
 * [config.site_name](../user-guide/configuration.md#site_name)
@@ -781,7 +781,7 @@ objects.
 ```
 
 If present, the `config` object contains the key/value pairs of config options
-defined for the plugin in the user's `mkdocs.yml` config file under
+defined for the plugin in the user's `properdocs.yml` config file under
 `plugings.search`. The `config` object was new in ProperDocs version *1.0*.
 
 The `docs` object contains a list of document objects. Each document object is
@@ -887,7 +887,7 @@ hyphens to separate words and including the name of your theme.
 Most of the rest of the file can be left unedited. The last section we need to
 change is the entry_points. This is how ProperDocs finds the theme(s) you are
 including in the package. The name on the left is the one that users will use
-in their mkdocs.yml and the one on the right is the directory containing your
+in their properdocs.yml and the one on the right is the directory containing your
 theme files.
 
 The directory you created at the start of this section with the main.html file
@@ -922,7 +922,7 @@ Then in a template, that config option could be referenced:
 {% endif %}
 ```
 
-And the user could override the default in their project's `mkdocs.yml` config
+And the user could override the default in their project's `properdocs.yml` config
 file:
 
 ```yaml
@@ -940,7 +940,7 @@ special options which alters its behavior:
 >
 > This option mirrors the [theme] config option of the same name. If this
 > value is not defined in the `mkdocs_theme.yml` file and the user does not
-> set it in `mkdocs.yml` then it will default to `en` (English). The value
+> set it in `properdocs.yml` then it will default to `en` (English). The value
 > is expected to match the language used in the text provided by the theme
 > (such a "next" and "previous" links) and should be used as the value of
 > the `<html>` tag's `lang` attribute. See [Supporting theme localization/

docs/dev-guide/translations.md

@@ -191,7 +191,7 @@ packages/properdocs-theme-mkdocs/properdocs_theme_mkdocs/locales
 Note that the compiled `messages.mo` file was generated based on the
 `messages.po` file that you just edited.
 
-Then modify the `mkdocs.yml` file at the root of the project to test the new
+Then modify the `properdocs.yml` file at the root of the project to test the new
 and/or updated locale:
 
 ```yaml
@@ -208,7 +208,7 @@ Finally, run `properdocs serve` to check out your new localized version of the t
 > actual text translation `messages.po` files (the rest is ignored by git).
 >
 > After you have finished testing your work, be sure to undo the change to
-> the `locale` setting in the `mkdocs.yml` file before submitting your
+> the `locale` setting in the `properdocs.yml` file before submitting your
 > changes.
 
 ## Updating theme documentation

docs/getting-started.md

@@ -28,13 +28,13 @@ Take a moment to review the initial project that has been created for you.
 
 ![The initial ProperDocs layout](img/initial-layout.png)
 
-There's a single configuration file named `mkdocs.yml`, and a folder named
+There's a single configuration file named `properdocs.yml`, and a folder named
 `docs` that will contain your documentation source files (`docs` is
 the default value for the [docs_dir] configuration setting). Right now the `docs`
 folder just contains a single documentation page, named `index.md`.
 
 ProperDocs comes with a built-in dev-server that lets you preview your documentation
-as you work on it. Make sure you're in the same directory as the `mkdocs.yml`
+as you work on it. Make sure you're in the same directory as the `properdocs.yml`
 configuration file, and then start the server by running the `properdocs serve`
 command:
 
@@ -43,7 +43,7 @@ $ properdocs serve
 INFO    -  Building documentation...
 INFO    -  Cleaning site directory
 INFO    -  Documentation built in 0.22 seconds
-INFO    -  [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml'
+INFO    -  [15:50:43] Watching paths for changes: 'docs', 'properdocs.yml'
 INFO    -  [15:50:43] Serving on http://127.0.0.1:8000/
 ```
 
@@ -60,7 +60,7 @@ Open the `docs/index.md` document in your text editor of choice, change the
 initial heading to `MkLorum`, and save your changes. Your browser will
 auto-reload and you should see your updated documentation immediately.
 
-Now try editing the configuration file: `mkdocs.yml`. Change the
+Now try editing the configuration file: `properdocs.yml`. Change the
 [`site_name`][site_name] setting to `MkLorum` and save the file.
 
 ```yaml
@@ -114,7 +114,7 @@ part!
 ## Theming our documentation
 
 Now change the configuration file to alter how the documentation is displayed by
-changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] setting:
+changing the theme. Edit the `properdocs.yml` file and add a [`theme`][theme] setting:
 
 ```yaml
 site_name: MkLorum

docs/user-guide/choosing-your-theme.md

@@ -8,7 +8,7 @@ ProperDocs includes two built-in themes ([mkdocs](#mkdocs) and
 [readthedocs](#readthedocs)), as documented below. However, many [third party
 themes] are available to choose from as well.
 
-To choose a theme, set the [theme] configuration option in your `mkdocs.yml`
+To choose a theme, set the [theme] configuration option in your `properdocs.yml`
 config file.
 
 ```yaml

docs/user-guide/configuration.md

@@ -7,7 +7,7 @@ Guide to all available configuration settings.
 ## Introduction
 
 Project settings are configured by default using a YAML configuration file in
-the project directory named `mkdocs.yml`. You can specify another path for it
+the project directory named `properdocs.yml`. You can specify another path for it
 by using the `-f`/`--config-file` option (see `properdocs build --help`).
 
 At a minimum, this configuration file must contain the `site_name`. All other settings are optional.
@@ -823,7 +823,7 @@ This alternative syntax is required if you intend to override some options via
 
 NEW: **New in version 1.4.**
 
-A list of paths to Python scripts (relative to `mkdocs.yml`) that are loaded and used as [plugin](#plugins) instances.
+A list of paths to Python scripts (relative to `properdocs.yml`) that are loaded and used as [plugin](#plugins) instances.
 
 For example:
 
@@ -884,7 +884,7 @@ the site. See the [Plugins] documentation for full details.
 
 **default**: `['search']` (the "search" plugin included with ProperDocs).
 
-If the `plugins` config setting is defined in the `mkdocs.yml` config file, then
+If the `plugins` config setting is defined in the `properdocs.yml` config file, then
 any defaults (such as `search`) are ignored and you need to explicitly re-enable
 the defaults if you would like to continue using them:
 
@@ -1115,7 +1115,7 @@ Examples of the possible values are:
 ```yaml
 - !relative  # Relative to the directory of the current Markdown file
 - !relative $docs_dir  # Path of the docs_dir
-- !relative $config_dir  # Path of the directory that contains the main mkdocs.yml
+- !relative $config_dir  # Path of the directory that contains the main properdocs.yml
 - !relative $config_dir/some/child/dir  # Some subdirectory of the root config directory
 ```
 
@@ -1131,12 +1131,12 @@ markdown_extensions:
 
 This allows the [pymdownx.snippets] extension to include files relative to the current Markdown file, which without this tag it would have no way of knowing.
 
-> NOTE: Even for the default case, any extension's base path is technically the *current working directory* although the assumption is that it's the *directory of mkdocs.yml*. So even if you don't want the paths to be relative, to improve the default behavior, always prefer to use this idiom:
+> NOTE: Even for the default case, any extension's base path is technically the *current working directory* although the assumption is that it's the *directory of properdocs.yml*. So even if you don't want the paths to be relative, to improve the default behavior, always prefer to use this idiom:
 >
 > ```yaml
 > markdown_extensions:
 >   - pymdownx.snippets:
->       base_path: !relative $config_dir  # Relative to the root directory with mkdocs.yml
+>       base_path: !relative $config_dir  # Relative to the root directory with properdocs.yml
 > ```
 
 ## Configuration Inheritance
@@ -1171,15 +1171,15 @@ markdown_extensions:
 ```
 
 Then, for the "foo" site, the primary configuration file would be defined at
-`foo/mkdocs.yml`:
+`foo/properdocs.yml`:
 
 ```yml
 INHERIT: ../base.yml
 site_name: Foo Project
 site_url: https://example.com/foo
 ```
 
-When running `properdocs build`, the file at `foo/mkdocs.yml` would be passed in as
+When running `properdocs build`, the file at `foo/properdocs.yml` would be passed in as
 the configuration file. ProperDocs will then parse that file, retrieve and parse the
 parent file `base.yml` and deep merge the two. This would result in ProperDocs
 receiving the following merged configuration:
@@ -1259,7 +1259,7 @@ path based options in the primary configuration file only.
 The inheritance can also be used as a quick way to override keys on the command line - by using stdin as the config file. For example:
 
 ```bash
-echo '{INHERIT: mkdocs.yml, site_name: "Renamed site"}' | properdocs build -f -
+echo '{INHERIT: properdocs.yml, site_name: "Renamed site"}' | properdocs build -f -
 ```
 
 [Theme Developer Guide]: ../dev-guide/themes.md

docs/user-guide/customizing-your-theme.md

@@ -27,7 +27,7 @@ h1 {
 }
 ```
 
-Then you need to add it to `mkdocs.yml`:
+Then you need to add it to `properdocs.yml`:
 
 ```yaml
 extra_css:
@@ -88,7 +88,7 @@ next to your `docs_dir`:
 mkdir custom_theme
 ```
 
-And then point your `mkdocs.yml` configuration file at the new directory:
+And then point your `properdocs.yml` configuration file at the new directory:
 
 ```yaml
 theme:

docs/user-guide/deploying-your-docs.md

@@ -54,7 +54,7 @@ structure:
 
 ```text
 my-project/
-    mkdocs.yml
+    properdocs.yml
     docs/
 orgname.github.io/
 ```
@@ -65,10 +65,10 @@ directories to the `orgname.github.io` repository and call the
 
 ```sh
 cd ../orgname.github.io/
-properdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master
+properdocs gh-deploy --config-file ../my-project/properdocs.yml --remote-branch master
 ```
 
-Note that you need to explicitly point to the `mkdocs.yml` configuration file as
+Note that you need to explicitly point to the `properdocs.yml` configuration file as
 it is no longer in the current working directory. You also need to inform the
 deploy script to commit to the `master` branch. You may override the default
 with the [remote_branch] configuration setting, but if you forget to change
@@ -124,7 +124,7 @@ should provide some general assistance.
 
 When you build your site (using the `properdocs build` command), all of the files
 are written to the directory assigned to the [site_dir] configuration option
-(defaults to `"site"`) in your `mkdocs.yaml` config file. Generally, you will
+(defaults to `"site"`) in your `properdocs.yml` config file. Generally, you will
 simply need to copy the contents of that directory to the root directory of your
 hosting provider's server. Depending on your hosting provider's setup, you may
 need to use a graphical or command line [ftp], [ssh] or [scp] client to transfer
@@ -203,7 +203,7 @@ a theme which includes all support files directly in the theme.
 
 When you build your site (using the `properdocs build` command), all of the files
 are written to the directory assigned to the [site_dir] configuration option
-(defaults to `"site"`) in your `mkdocs.yaml` config file. Generally, you will
+(defaults to `"site"`) in your `properdocs.yml` config file. Generally, you will
 simply need to copy the contents of that directory and distribute it to your
 readers. Alternatively, you may choose to use a third party tool to convert the
 HTML files to some other documentation format.