-
Notifications
You must be signed in to change notification settings - Fork 75
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Automatically slugify site_name #58
Merged
iamEAP
merged 9 commits into
backstage:master
from
diegomarangoni:add-site-name-slugify
Oct 27, 2021
Merged
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
57eba4e
change getAlias to convert site_name to a slug
diegomarangoni b98f9b6
Update unit tests to work with slugs
diegomarangoni 3f728e5
Remove limitation
diegomarangoni 61510dc
Bump plugin version
diegomarangoni d71cb03
Slugify only if didn't match regex
diegomarangoni 37f7b33
Use slugify library compatible with python 3.5
diegomarangoni a1c96e3
Rename test fixtures.
iamEAP 802f89a
Prepare for patch release.
iamEAP 5c1af83
Merge branch 'master' into add-site-name-slugify
iamEAP File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -121,7 +121,7 @@ teardown() { | |
@test "builds a mkdocs site with site_name containing slash" { | ||
cd ${fixturesDir}/ok-nested-site-name-contains-slash | ||
assertSuccessMkdocs build | ||
assertFileExists site/plugins/example-Folder/index.html | ||
assertFileExists site/plugins-example-folder/index.html | ||
[[ "$output" == *"This contains a sentence which only exists in the ok-nested-site-name-contains-slash/project-a fixture."* ]] | ||
} | ||
|
||
|
@@ -139,6 +139,11 @@ teardown() { | |
[[ "$output" == *"This contains a sentence which only exists in the ok-mkdocs-git-revision-date-localized-plugin/project-a fixture."* ]] | ||
} | ||
|
||
@test "builds a mkdocs even if !include path has site_name containing spaces" { | ||
cd ${fixturesDir}/error-include-path-site-name-contains-space | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Just one last update and I think this is good to merge. Could you update the name of this fixture to indicate that no error is expected? Maybe even just |
||
assertSuccessMkdocs build | ||
} | ||
|
||
@test "fails if !include path is above current folder" { | ||
cd ${fixturesDir}/error-include-path-is-parent | ||
assertFailedMkdocs build | ||
|
@@ -151,12 +156,6 @@ teardown() { | |
[[ "$output" == *"[mkdocs-monorepo] We currently do not support nested !include statements inside of Mkdocs."* ]] | ||
} | ||
|
||
@test "fails if !include path has site_name containing spaces" { | ||
cd ${fixturesDir}/error-include-path-site-name-contains-space | ||
assertFailedMkdocs build | ||
[[ "$output" == *"[mkdocs-monorepo] Site name can only contain letters, numbers, underscores, hyphens and forward-slashes. The regular expression we test against is '^[a-zA-Z0-9_\-/]+$'."* ]] | ||
} | ||
|
||
@test "fails if !include paths contains duplicate site_name values" { | ||
cd ${fixturesDir}/error-include-paths-duplicate-site-name | ||
assertFailedMkdocs build | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,3 @@ | ||
# Caveats / Known Design Decisions | ||
|
||
- In an included `mkdocs.yml`, you cannot have `!include`. It is only supported in the root `mkdocs.yml` | ||
- In an included `mkdocs.yml`, your `site_name` must adhere follow the regular expression: `^[a-zA-Z0-9_\-/]+$` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like a "/" should not be replaced by "-" in the path because apparently, it causes a not found error that has been solved in the past here:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I will change a bit, I will slugify only if doesn't match the regex
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
if I use disallowed characters (like "@"), it compiles, but some pages are not found:
sample-docs/v3/mkdocs.yml
![image](https://user-images.githubusercontent.com/6290749/137900416-879de2a6-2db9-4087-8ec3-6af79420cc68.png)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
slugified
site_name
will naturally have different paths than the ones matching the regexin this specific case, it will require to change the link reference to
./versions-v3/reference.md
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So this will introduce significant changes, if we continue, it would be good to have instructions for this new path pattern. I'd like to hear from other reviewers just to make sure it's okay to proceed with this new standard.
What do you think @emmaindal, @iamEAP, @ottosichert and @OrkoHunter?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can somebody map out from a product perspective what the implications of this suggested change are?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Correct me @diegomarangoni, if am I wrong, please 🙏🏻
What will change is that we will replace all invalid characters with "-" in the
site_name
when generating documentation without throwing an error with instructions to not use those characters there.The consequences are:
Example:
This is a new link path using "versions-v3" instead of "versions/v3:
![slugify](https://user-images.githubusercontent.com/6290749/138054781-f7a3b661-8bf2-4491-bc39-860d19fe50e9.png)
If you try to access the page using the previous URL will see a not found page:
And if you don't update the link in your markdown, they will be broken links pointing to the old URL (not found pages):
To fix this, users will need to update the paths in their doc files:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes, that's correct, but there is one important difference:
if you don't change your
site_name
and continue to use the pattern matching regex (^[a-zA-Z0-9_\-/]+$
), nothing changesthese consequences you mentioned only apply to cases where you decided to change your
site_name
to something that does not match the regex