Automatically slugify site_name #58

diegomarangoni · 2021-10-12T08:50:15Z

Currently, this plugin fails if an embedded mkdocs site_name field does not match the regex ^[a-zA-Z0-9_\-/]+$.

This PR change this behavior to automatically generate a slug based on site_name, this will allow to maintain user-friendly names and still be able to embed.

diegomarangoni · 2021-10-15T08:24:24Z

can I have a review here? maybe @bih?

camilaibs · 2021-10-18T14:25:29Z

Starting to review

camilaibs · 2021-10-19T08:29:32Z

__tests__/integration/test.bats

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


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:

Issue: Broken version 0.4.9 #23

Pull request: use os.path.join instead of convert '/' to '-' #24

I will change a bit, I will slugify only if doesn't match the regex

if I use disallowed characters (like "@"), it compiles, but some pages are not found:

sample-docs/v3/mkdocs.yml

slugified site_name will naturally have different paths than the ones matching the regex
in this specific case, it will require to change the link reference to ./versions-v3/reference.md

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?

Can somebody map out from a product perspective what the implications of this suggested change are?

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:

Users will lose favorite links that point to the current path style

And should also update links in their markdown files to use the new path pattern instead (the breaking change)

Example:

This is a new link path using "versions-v3" instead of "versions/v3:

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:

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 changes

these consequences you mentioned only apply to cases where you decided to change your site_name to something that does not match the regex

camilaibs · 2021-10-19T09:13:18Z

Hello, @diegomarangoni thanks for contributing 🎉
Added only one comment to the test file!
Can you take a look at the failed checks, please?

diegomarangoni · 2021-10-19T10:30:50Z

hey @camilaibs, thanks for the review

I did some changes, it should works now

garyniemen · 2021-10-22T09:12:01Z

@diegomarangoni - I have been thinking about this a bit. We are a bit reluctant to introduce an automatic change to a user's site_name (assuming they have used a character that doesn't pass the regex). I think the favoured solution would be to inform the user that their site_name includes an invalid character - and then give a good error message that guides them in the right direction. And I think we have that in place, right @camilaibs ?
Please let me know though @diegomarangoni if I have misunderstood the problem that you are trying to solve and your attempt to solve it.

camilaibs · 2021-10-22T09:21:15Z

@diegomarangoni - I have been thinking about this a bit. We are a bit reluctant to introduce an automatic change to a user's site_name (assuming they have used a character that doesn't pass the regex). I think the favoured solution would be to inform the user that their site_name includes an invalid character - and then give a good error message that guides them in the right direction. And I think we have that in place, right @camilaibs ? Please let me know though @diegomarangoni if I have misunderstood the problem that you are trying to solve and your attempt to solve it.

Hey @garyniemen, the message we have today is:

"Site name can only contain letters, numbers, underscores, hyphens and forward-slashes. The regular expression we test against is ^[a-zA-Z0-9_\-/]+$."

diegomarangoni · 2021-10-22T10:09:36Z

hey @garyniemen, let me better explain the use case this PR is intended to solve.

Currently, this plugin requires that every included documentation must be designed to be embedded, meaning the site_name instead of being used as page title, will be used as the navigation path.

Considering a scenario where the documentation is designed to have its own dedicated page, with site_name being a human-friendly title, embedding this doc would not be possible.

So this will require changing the documentation title to something less user-friendly and also assumes that the user has control over this project, which might not be the case.

Let me know if you have any question

iamEAP · 2021-10-25T12:14:33Z

__tests__/integration/test.bats

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


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 no-error-include-path-site-name-contains-space

garyniemen · 2021-10-26T10:13:31Z

Hi again @diegomarangoni - sorry for the delay in replying. I am still a bit confused. Is this use case specifically for a Monorepo? Assuming so, and within that context, can you describe what the 2 use cases are that you are trying to simultaneously address. Will the change that you are making fix one of these use cases - but still keep the other working fine? And - what is the relation between these 2 use cases and the previous discussion around Regex?

diegomarangoni · 2021-10-27T07:54:56Z

hey @garyniemen, the use case I describe is for multiple repositories, let me bring an example that might help:

I have 3 repositories:

myapp-backend: it has his own mkdocs file, his own mkdocs serve page, and the site_name being MyApp Backend service
myapp-frontend: like the previous one, but I don't have control over this repository and site_name being MyApp Frontend application
myapp-docs: new repository created in order to centralize backend and frontend docs in a single place

So the problem here is that I can't easily use this plugin without having to change both frontend and backend site_name first and at the cost of having less friendly titles on their mkdocs serve page

Here is how the page looks like:

.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

iamEAP · 2021-10-27T13:06:22Z

Thanks for the contribution @diegomarangoni! Shipping this now as a patch release. Will look toward the .yaml support PR as a minor version update after this.

diegomarangoni added 4 commits October 12, 2021 10:37

change getAlias to convert site_name to a slug

57eba4e

Update unit tests to work with slugs

b98f9b6

Remove limitation

3f728e5

Bump plugin version

61510dc

diegomarangoni requested a review from a team as a code owner October 12, 2021 08:50

camilaibs reviewed Oct 19, 2021

View reviewed changes

diegomarangoni added 2 commits October 19, 2021 12:29

Slugify only if didn't match regex

d71cb03

Use slugify library compatible with python 3.5

37f7b33

iamEAP reviewed Oct 25, 2021

View reviewed changes

iamEAP and others added 3 commits October 27, 2021 14:57

Rename test fixtures.

a1c96e3

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

Prepare for patch release.

802f89a

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

Merge branch 'master' into add-site-name-slugify

5c1af83

iamEAP approved these changes Oct 27, 2021

View reviewed changes

iamEAP merged commit c06c481 into backstage:master Oct 27, 2021

camilaibs mentioned this pull request Dec 15, 2021

Allow for spaces in site_name of sub-docs #56

Closed

camilaibs linked an issue Dec 15, 2021 that may be closed by this pull request

Allow for spaces in site_name of sub-docs #56

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Automatically slugify site_name #58

Automatically slugify site_name #58

diegomarangoni commented Oct 12, 2021

diegomarangoni commented Oct 15, 2021

camilaibs commented Oct 18, 2021

camilaibs Oct 19, 2021 •

edited

Loading

diegomarangoni Oct 19, 2021

camilaibs Oct 19, 2021 •

edited

Loading

diegomarangoni Oct 19, 2021 •

edited

Loading

camilaibs Oct 19, 2021

garyniemen Oct 20, 2021 •

edited

Loading

camilaibs Oct 20, 2021 •

edited

Loading

diegomarangoni Oct 20, 2021

camilaibs commented Oct 19, 2021

diegomarangoni commented Oct 19, 2021

garyniemen commented Oct 22, 2021

camilaibs commented Oct 22, 2021

diegomarangoni commented Oct 22, 2021

iamEAP Oct 25, 2021

garyniemen commented Oct 26, 2021 •

edited

Loading

diegomarangoni commented Oct 27, 2021

iamEAP commented Oct 27, 2021

Automatically slugify site_name #58

Automatically slugify site_name #58

Conversation

diegomarangoni commented Oct 12, 2021

diegomarangoni commented Oct 15, 2021

camilaibs commented Oct 18, 2021

camilaibs Oct 19, 2021 • edited Loading

Choose a reason for hiding this comment

diegomarangoni Oct 19, 2021

Choose a reason for hiding this comment

camilaibs Oct 19, 2021 • edited Loading

Choose a reason for hiding this comment

diegomarangoni Oct 19, 2021 • edited Loading

Choose a reason for hiding this comment

camilaibs Oct 19, 2021

Choose a reason for hiding this comment

garyniemen Oct 20, 2021 • edited Loading

Choose a reason for hiding this comment

camilaibs Oct 20, 2021 • edited Loading

Choose a reason for hiding this comment

diegomarangoni Oct 20, 2021

Choose a reason for hiding this comment

camilaibs commented Oct 19, 2021

diegomarangoni commented Oct 19, 2021

garyniemen commented Oct 22, 2021

camilaibs commented Oct 22, 2021

diegomarangoni commented Oct 22, 2021

iamEAP Oct 25, 2021

Choose a reason for hiding this comment

garyniemen commented Oct 26, 2021 • edited Loading

diegomarangoni commented Oct 27, 2021

iamEAP commented Oct 27, 2021

camilaibs Oct 19, 2021 •

edited

Loading

camilaibs Oct 19, 2021 •

edited

Loading

diegomarangoni Oct 19, 2021 •

edited

Loading

garyniemen Oct 20, 2021 •

edited

Loading

camilaibs Oct 20, 2021 •

edited

Loading

garyniemen commented Oct 26, 2021 •

edited

Loading