Exclude link targets when using strict mode? #2957
Replies: 3 comments 1 reply
-
Side note: I am interested in which solution you arrived at, currently looking for ideas in this space and how to improve mkdocstrings. And does this mean that your API pages have a totally different style, not themed to mkdocs? Or how do you inject them? It's important. |
Beta Was this translation helpful? Give feedback.
-
My advice is not a direct answer to the title, but instead a better suggestion: I assume that you have some files originating from outside, that wasn't precisely specified. Then the core of the suggestion: The way that MkDocs checks for links' validity is checking if they're in the import os.path
import tempfile
from mkdocs.structure.files import File
my_src_dir = tempfile.TemporaryDirectory(prefix='my_src_dir_')
def on_files(files, config):
generated = ['foo.html']
for fn in generated:
with open(os.path.join(my_src_dir.name, fn), 'w') as f:
f.write("hi")
f = File(
fn,
src_dir=my_src_dir.name,
dest_dir=config['site_dir'],
use_directory_urls=config['use_directory_urls'],
)
files.append(f)
return files To achieve that, you can do one of these:
Since you're not providing an exact example of what you currently have, I am not writing a complete code example either, I don't want to guess and make up an example from scratch myself. Otherwise, would love to. |
Beta Was this translation helpful? Give feedback.
-
Thanks for such a thorough answer even with our limited info! So our solution was to create empty markdown-files in the repository for all our API endpoint pages that we would generate and need links for. A few index-pages with actual content was also created. The generated markdown files (based on an OpenAPI specification) will then overwrite the empty endpoint-pages in our Jenkins build pipeline. At the same time we generate a new So a summary: Here's the result: https://docs.apptus.com/esales-4/integration/api/specification/ |
Beta Was this translation helpful? Give feedback.
-
We've been running our MkDocs installation in
strict
mode since 2017 and it's such a great and easy way to check if your links are in order. However, we've now started to automatically generate parts of our documentation directly from our API and then injecting it in our build process before the rest of the site is generated.This has resulted in the issue that all our links to those pages now fail when using
mkdocs serve
locally and we receive 70+ errors. As I see it, at the moment I have one option to retain localserve
functionality to keep usingstrict
for build and internal link validation - convert all our links to absolute URLs as they are not affected bystrict
.This will however cause issues in our docs development environment as we automatically create sites for internal review based on the active branch we use, and the links would point to our live documentation.
I've checked #1443 and adding a setting such as
exclude_targets
or similar will most likely not be added, and I haven't seem to find a plugin that have this functionality.Does anyone have any suggestions for either a plugin (that I've missed) or any other method or workaround to still run
strict
mode to check my links on serve/build while not failing for a sub set of target pages?Beta Was this translation helpful? Give feedback.
All reactions