mirror of
https://github.com/cockpit-project/cockpit.git
synced 2026-11-03 21:49:50 -09:00
bc62cb3709
Antora uses a dedicated folder structure which we need to adhere to for it to work as it should. Makefiles has moved to `doc/` root to simplify the approach needed with Antora and AsciiDoctor. Existing bundling of documentation with help of AsciiDoctor works as normal and does not interfere with the directory change. Signed-off-by: Freya Gustavsson <freya@venefilyn.se>
71 lines
2.7 KiB
Text
71 lines
2.7 KiB
Text
[[urls]]
|
|
= Cockpit URLs
|
|
|
|
Cockpit URLs follow a specific structure, related to the components they
|
|
are loading. Various components are loaded in `+<iframe>+` tags. The
|
|
URLs for these components are described first. Further down below you
|
|
can find information about the top level bookmarkable Cockpit address
|
|
URLs.
|
|
|
|
[[urls-components]]
|
|
== Component URLs
|
|
|
|
Cockpit components are HTML documents. They are organized into
|
|
link:#packages[packages]. Each package contains information about which
|
|
HTML components are available in that package. Components should always
|
|
use relative URLs to access resources, such as images, scripts or CSS
|
|
files, even if they refer to a resource in another package.
|
|
|
|
The following are valid component URLs, each bit will be discussed
|
|
below:
|
|
|
|
....
|
|
/cockpit/@localhost/package/component.html#/hash
|
|
/cockpit/$checksum/package/component.html#/hash
|
|
/cockpit/@server.example.com/package/component.html#/hash
|
|
/cockpit+embedder/@localhost/package/component.html#/hash
|
|
....
|
|
|
|
All resource URLs are under the `+/cockpit+` namespace. In cases where a
|
|
Cockpit component is being link:#embedding[embedded] the `+/cockpit+`
|
|
may be followed by a plus sign and another `+embedder+` specific
|
|
identifier.
|
|
|
|
What follows is either a `+@host+` or `+$checksum+` which tells cockpit
|
|
where to link:#packages[find the package]. Checksums are used when more
|
|
than one host has identical packages and the resources can be cached.
|
|
|
|
The `+package+` name is next, followed by the `+component+` HTML path
|
|
inside that package. And lastly a hash allows for navigation within a
|
|
single component. The hash should follow a URL path and/or query string
|
|
form.
|
|
|
|
[WARNING]
|
|
====
|
|
Never assume that the `+@host+` or `+$checksum+` portion is predictable.
|
|
Only refer to resources in packages on the same host.
|
|
====
|
|
|
|
[[urls-visible]]
|
|
== Visible URLs
|
|
|
|
The above Component URLs are usually not visible to the user. Instead
|
|
the Cockpit Web Service wraps the components in a shell which allows
|
|
navigation, and provides bookmarkable clean URLs to the component. These
|
|
URLs do not affect link:#embedding[embedders] or
|
|
link:#packages[components] directly.
|
|
|
|
If no path is present then the Cockpit will redirect to the default page
|
|
for the server.
|
|
|
|
If the first segment of the path begins with an `+@+` sign, then the
|
|
component is being shown from a non-local host.
|
|
|
|
The next segment of the path, (or first if the component is being shown
|
|
on the local host) is the link:#packages[package name]. The remainder of
|
|
the path is a component file in the package. If no further path segments
|
|
are present, a default `+index.html+` component in the package is
|
|
loaded. An extension of `+.html+` is automatically appended.
|
|
|
|
The hash portion of the path is automatically transferred to the
|
|
component as the hash of its link:#urls-components[resource URL].
|