unrecognized relative link

[rwmoose]

This may be perfectlly normal, but I wanted to verify.

I have the following placeholder setup

settings:
  expand_auto_tables: true
  auto_placeholder_tables: false
  normal_is_alias_for: dynamic
placeholders:
  SERVERIP:
    description: "Linux VM IP Address (mandatory)"
    default: "192.168.100.100"
    validators: ipv4_address
  FQDN:
    description: "Application FQDN"
    default: "xSERVERIPx.nip.io"
    validators: domain
    allow_nested: true
    read_only: true
    replace_everywhere: true
  FQDN_URL:
    description: "Application URL"
    default: "https://xFQDNx"
    validators: url_http
    allow_nested: true
    read_only: true
    replace_everywhere: true

and in my markdown, I have the following:

Log into your application UI at the following URL:

- [sFQDN_URLs](iFQDN_URLi)

everything works fine, but in my mkdocs log, I get the following:

INFO    -  Doc file 'quickstart/AppInstall.md' contains an unrecognized relative link 'iFQDN_URLi', it was left as is.

Everything works fine. Just wondering if this is expected, or am I missing something in my config. Thanks

[six-two]

Hi and thank you for reporting this. I would say this is expected behavior. When MkDocs parses the markdown and converts it to HTML during the build process, it converts the ‘[title](iFQDN_URLi)’ to something like ‘<a href=“iFQDN_URLi”>title</a>’. As it is a static site generator, it finds this URL suspicious (it is not a URL or name of an existing page), so it warns you. When a user loads the page, the iFQDN_URLi value is replaced with a user specified value and the link should point to a valid URL. But MkDocs does not know/expect that this would happen. In a couple weeks when I can try to code a workaround to fix the warning. I have some ideas, but am traveling without my laptop so I can not try them. PS: In case you do not edit FQDN_URL (it is readonly), you could hardcode “ https://iFQDNi” instead of using iFQDN_URLi and the warning should no longer appear. Because then the link would look like an actual URL during the build process.

…

On Tue, Oct 7, 2025 at 17:56 Steve ***@***.***> wrote: *rwmoose* created an issue (six-two/mkdocs-placeholder-plugin#12) <#12> This may be perfectlly normal, but I wanted to verify. I have the following placeholder setup settings: expand_auto_tables: true auto_placeholder_tables: false normal_is_alias_for: dynamicplaceholders: SERVERIP: description: "Linux VM IP Address (mandatory)" default: "192.168.100.100" validators: ipv4_address FQDN: description: "Application FQDN" default: "xSERVERIPx.nip.io" validators: domain allow_nested: true read_only: true replace_everywhere: true FQDN_URL: description: "Application URL" default: "https://xFQDNx" validators: url_http allow_nested: true read_only: true replace_everywhere: true and in my markdown, I have the following: Log into your application UI at the following URL: - [sFQDN_URLs](iFQDN_URLi) everything works fine, but in my mkdocs log, I get the following: INFO - Doc file 'quickstart/AppInstall.md' contains an unrecognized relative link 'iFQDN_URLi', it was left as is. Everything works fine. Just wondering if this is expected, or am I missing something in my config. Thanks — Reply to this email directly, view it on GitHub <#12>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AE2QXX5NBM3QJZ7UT7637OD3WPPBHAVCNFSM6AAAAACIQ6CPWGVHI2DSMVQWIX3LMV43ASLTON2WKOZTGQ4TEMBWHE3TSMA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[rwmoose]

that worked like a champ. Thanks for the suggestion.

Log into your application UI at the following URL:

- [sFQDN_URLs](https://iFQDNi)

[six-two]

@rwmoose I also implemented a workaround, in case the url scheme (like https://) can not be hardcoded. You can now write inline placeholders as x-placeholder-link://iFQDN_URLi which should also not be flagged as a unknown URL by mkdocs. See https://dev.mkdocs-placeholder-plugin.six-two.dev/configuration/#html_prefix_optional.

I'd be grateful if you could try that out and report any bugs you notice :)

[rwmoose]

Just got back from vacation. I'll try it out tomorrow. thanks for the quick response.

[rwmoose]

So just did a quick test. Iset up the placeholder tlike this.

  FQDN_URL:
    description: "Application URL"
    default: "https://xFQDNx"
    validators: url_http
    allow_nested: true
    read_only: true
    replace_everywhere: true

[sFQDN_URLs](https://iFQDNi). - same results.

[sFQDN_URLs](x-placeholder-link://iFQDN_URLi). - This worked fine. no alerts.

As long as the URL is was (http://x.com works, https://x.com worked, text://x.com failed)

I did try to add in the html_prefix_optional setting,

settings:
  expand_auto_tables: true
  auto_placeholder_tables: false
  normal_is_alias_for: dynamic
  html_prefix_optional: "http://"

but it failed on whenever i ran mkdocs serve. Running (version 0.5.1).

so by using [sFQDN_URLs](x-placeholder-link://iFQDN_URLi), my problem is solved (thank you) Hope this information is helpful

WARNING -  [placeholder] Fatal exception occurred, stack trace:
           Traceback (most recent call last):
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/generic/config/parser_utils.py", line
           27, in wrap
               return function(data, location, *args, **kwargs)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/generic/config/configuration.py", line
           80, in parse_settings
               assert_no_unknown_fields(data, SETTINGS_FIELD_NAMES)
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/generic/config/parser_utils.py", line
           21, in assert_no_unknown_fields
               raise PlaceholderConfigError(f"Unexpected field(s): {', '.join(unexpected_fields)}\n[Hint] Allowed fields are:
           {', '.join(known_field_names)}")
           mkdocs_placeholder_plugin.generic.PlaceholderConfigError: Unexpected field(s): html_prefix_optional
           [Hint] Allowed fields are: editable_prefix, replace_delay_millis, show_warnings, normal_is_alias_for,
           dynamic_prefix, html_suffix, normal_suffix, editable_suffix, auto_placeholder_tables, static_suffix,
           apply_change_on_focus_change, static_prefix, create_no_js_fallback, debug_javascript, expand_auto_tables,
           normal_prefix, inline_editor_style, inline_editors, dynamic_suffix, html_prefix

           During handling of the above exception, another exception occurred:

           Traceback (most recent call last):
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/mkdocs/plugin.py", line 19, in wrap
               return function(*args, **kwargs)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/mkdocs/plugin.py", line 40, in on_config
               self.configuration = initialize_plugin(config, self.config)
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/mkdocs/utils.py", line 21, in
           initialize_plugin
               placeholder_config = find_and_parse_configuration_file(mkdocs_config, plugin_config)
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/mkdocs/utils.py", line 49, in
           find_and_parse_configuration_file
               return parse_configuration_file(plugin_config.placeholder_file)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/generic/config/configuration.py", line
           132, in parse_configuration_file
               return parse_configuration(data, path)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/generic/config/parser_utils.py", line
           27, in wrap
               return function(data, location, *args, **kwargs)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/generic/config/configuration.py", line
           142, in parse_configuration
               settings = parse_settings(settings_data, f"{location}.settings")
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/usr/local/lib/python3.11/site-packages/mkdocs_placeholder_plugin/generic/config/parser_utils.py", line
           35, in wrap
               raise PlaceholderConfigErrorWithData(message, location, data)
           mkdocs_placeholder_plugin.generic.config.parser_utils.PlaceholderConfigErrorWithData: Unexpected field(s):
           html_prefix_optional
           [Hint] Allowed fields are: editable_prefix, replace_delay_millis, show_warnings, normal_is_alias_for,
           dynamic_prefix, html_suffix, normal_suffix, editable_suffix, auto_placeholder_tables, static_suffix,
           apply_change_on_focus_change, static_prefix, create_no_js_fallback, debug_javascript, expand_auto_tables,
           normal_prefix, inline_editor_style, inline_editors, dynamic_suffix, html_prefix

           Caused by data at config/placeholder-plugin.yaml.settings: {
               "expand_auto_tables": true,
               "auto_placeholder_tables": false,
               "normal_is_alias_for": "dynamic",
               "html_prefix_optional": "http://"
           }
ERROR   -  Unexpected field(s): html_prefix_optional
           [Hint] Allowed fields are: editable_prefix, replace_delay_millis, show_warnings, normal_is_alias_for,
           dynamic_prefix, html_suffix, normal_suffix, editable_suffix, auto_placeholder_tables, static_suffix,
           apply_change_on_focus_change, static_prefix, create_no_js_fallback, debug_javascript, expand_auto_tables,
           normal_prefix, inline_editor_style, inline_editors, dynamic_suffix, html_prefix

           Caused by data at config/placeholder-plugin.yaml.settings: {
               "expand_auto_tables": true,
               "auto_placeholder_tables": false,
               "normal_is_alias_for": "dynamic",
               "html_prefix_optional": "http://"
           }

[six-two]

@rwmoose Thanks for testing. Your last stacktrace Unexpected field(s): html_prefix_optional looks like you are using the stable version, which does not contain my change. Could you install this fixed version please:

pip install mkdocs-placeholder-plugin==0.5.2.dev1