Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Support default document (index.html) for cleaner URLs #1346

Closed
eseidelGoogle opened this issue Feb 17, 2017 · 6 comments · Fixed by #3895
Closed

Support default document (index.html) for cleaner URLs #1346

eseidelGoogle opened this issue Feb 17, 2017 · 6 comments · Fixed by #3895
Assignees
@srawlins
Labels
customer-flutter Issues originating from important to Flutter customer-google3 Issues originating from or important to Angular P2 A bug or feature request we're likely to work on type-enhancement A request for a change that isn't a bug

Comments

@eseidelGoogle
Copy link
Contributor

Right now to actually get to a library root page you need to know dartdocs pattern of doing name-library.html:
https://docs.flutter.io/flutter/dart-async/dart-async-library.html

https://docs.flutter.io/flutter/dart-async/
would just get you a 404.

Obviously we could fix this in Flutter's doc generation script as well, but seems like something maybe all dartdoc users might want?
@eseidelGoogle eseidelGoogle added the customer-flutter Issues originating from important to Flutter label Feb 17, 2017
@sethladd
Copy link
Contributor

Presumably this means there is an index.html under dart-async/. Could there be a thing called "index" inside of a Dart library? If so, what kind of structure would we need to put all the things into sub-directories so that they don't collide with a name called "index" ?

We might be able to teach Firebase what the "index.html" file is actually called. But, that would be a solution specific to Flutter's docs. I think assuming an "index.html" is a safe assumption, so many web servers will look for that file.

Just need to be careful here with collisions... but yeah, +1 for anything we can do for more beautiful URLs

@jcollins-g jcollins-g added the P3 A lower priority bug or feature request label May 22, 2017
@kevmoo kevmoo added type-enhancement A request for a change that isn't a bug P2 A bug or feature request we're likely to work on customer-google3 Issues originating from or important to Angular and removed P3 A lower priority bug or feature request labels Mar 21, 2018
@kevmoo
Copy link
Member

kevmoo commented Mar 21, 2018

https://api.dartlang.org/stable/1.24.3/dart-core/

Is soooo much nicer than

https://api.dartlang.org/stable/1.24.3/dart-core/dart-core-library.html

@guidezpl guidezpl mentioned this issue May 23, 2022
Open
@kevmoo
Copy link
Member

kevmoo commented Feb 14, 2024

CC @athomas

@kevmoo kevmoo changed the title Would be nice if docs/library_name/ worked instead of docs/library_name/library_name-library.html Support default document (index.html) for cleaner URLs Feb 14, 2024
@srawlins srawlins mentioned this issue Mar 26, 2024
Closed
@srawlins srawlins self-assigned this Oct 2, 2024
srawlins added a commit to srawlins/dartdoc that referenced this issue Oct 2, 2024
@srawlins
Introduce a new URL for library pages, at index.html
fa212e1 
Fixes dart-lang#1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
@srawlins srawlins mentioned this issue Oct 2, 2024
Merged
1 task
@srawlins
Copy link
Member

srawlins commented Oct 2, 2024

CC @kevmoo @gspencergoog would you say this is still very desirable? I have a PR out.

Re collisions, @sethladd, good catch! Most pages are suffixed with a 'kind', like Ticker-class.html, but enums (AppLifecycleState), properties (channelBuffers), functions (clampDouble), typedefs (ChannelCallback) are not suffixed, so any named index would collide with this. With that lower-case, this would particularly be a top-level property or top-level function that could cause a collision. I should probably use new paths for those like clampDouble-function.html, and write redirecting files.

srawlins added a commit to srawlins/dartdoc that referenced this issue Oct 3, 2024
@srawlins
Introduce a new URL for library pages, at index.html
75c4956 
Fixes dart-lang#1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
srawlins added a commit to srawlins/dartdoc that referenced this issue Oct 8, 2024
@srawlins
Introduce a new URL for library pages, at index.html
1c6d2f9 
Fixes dart-lang#1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
srawlins added a commit to srawlins/dartdoc that referenced this issue Oct 8, 2024
@srawlins
Introduce a new URL for library pages, at index.html
12113f2 
Fixes dart-lang#1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
srawlins added a commit to srawlins/dartdoc that referenced this issue Oct 8, 2024
@srawlins
Introduce a new URL for library pages, at index.html
64dda21 
Fixes dart-lang#1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
@kevmoo
Copy link
Member

kevmoo commented Oct 8, 2024

I think this is still VERY desirable.

@gspencergoog
Copy link
Collaborator

Yes, I agree.

srawlins added a commit to srawlins/dartdoc that referenced this issue Oct 9, 2024
@srawlins
Introduce a new URL for library pages, at index.html
ed58ede 
Fixes dart-lang#1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
srawlins added a commit to srawlins/dartdoc that referenced this issue Oct 9, 2024
@srawlins
Introduce a new URL for library pages, at index.html
114c817 
Fixes dart-lang#1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
srawlins added a commit that referenced this issue Oct 15, 2024
@srawlins
Introduce a new URL for library pages, at index.html (#3895)
7e503c1 
Fixes #1346

This "moves" the URL of each library from, e.g.
'package-two_lib2/package-two_lib2-library.html' to
'package-two_lib2/index.html', such that we can have links with
'package-two_lib2'. The old URLs are preserved via redirecting HTML files.

(HTTP redirects are more standard and recommended, but dartdoc does not contain
an HTTP server; HTTP redirects could be implemented at the hosting server,
which is different for different doc hosts (Google Storage, Firebase, ...).
Instead we use simpler HTML redirects. In fact, a given backend host could use
the HTML redirecting files as a database to inform HTTP redirect rules, that
need to be implemented differently for each backend. So dartdoc now produces
redirecting files, but a given backend could instead return an HTTP 301
Permanent Redirect response when requesting one of the redirecting files.)

This adds a negligible number of files (1 per documented library), and a
negligible number of bytes (tiny redirect files), but actually is probably a
net negative in terms of bytes, as many links are now shortened, removing the
HTML file name of library URLs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@srawlins srawlins

Labels
customer-flutter Issues originating from important to Flutter customer-google3 Issues originating from or important to Angular P2 A bug or feature request we're likely to work on type-enhancement A request for a change that isn't a bug
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Introduce a new URL for library pages, at index.html srawlins/dartdoc
6 participants
@sethladd @kevmoo @srawlins @gspencergoog @eseidelGoogle @jcollins-g