Page MenuHomestyx hydra
Files F1993583

No OneTemporary
Actions

View Options

diff --git a/.divinerconfig b/.divinerconfig
index 88c73c168f..b5c38d4aed 100644
--- a/.divinerconfig
+++ b/.divinerconfig
@@ -1,23 +1,23 @@
{
"name" : "Phabricator",
"src_base" : "https://github.com/facebook/phabricator/blob/master",
"groups" : {
"intro" : "Introduction",
"install" : "Installing",
"config" : "Configuration",
"userguide" : "Application User Guides",
-
+ "developer" : "Phabricator Developer Guides",
"differential" : "Differential (Code Review)",
"diffusion" : "Diffusion (Repository Browser)",
"maniphest" : "Maniphest (Task Tracking)",
"celerity" : "Celerity (CSS/JS Management)",
"aphront" : "Aphront (Web Stack)",
"console" : "DarkConsole (Debugging Console)",
"storage" : "Storage"
},
"engines" : [
["DivinerArticleEngine", {}],
["DivinerXHPEngine", {}]
]
}
diff --git a/src/docs/adding_new_css_and_js.diviner b/src/docs/adding_new_css_and_js.diviner
new file mode 100644
index 0000000000..f5ee9ef8e0
--- /dev/null
+++ b/src/docs/adding_new_css_and_js.diviner
@@ -0,0 +1,77 @@
+@title Adding New CSS and JS
+@group developer
+
+Explains how to add new CSS and JS files to Phabricator.
+
+= Overview =
+
+Phabricator uses a system called **Celerity** to manage static resources. If you
+are a current or former Facebook employee, Celerity is based on the Haste system
+used at Facebook and generally behaves similarly.
+
+= Adding a New File =
+
+To add a new CSS or JS file, create it in an appropriate location in
+##webroot/rsrc/css/## or ##webroot/rsrc/js/## inside your ##phabricator/##
+directory.
+
+Each file must ##@provides## itself as a component, declared in a header
+comment:
+
+ LANG=css
+ /**
+ * @provides duck-styles-css
+ */
+
+ .duck-header {
+ font-size: 9001px;
+ }
+
+Note that this comment must be a Javadoc-style comment, not just any comment.
+
+If your component depends on other components (which is common in JS but
+rare and inadvisable in CSS), declare then with ##@requires##:
+
+ LANG=js
+ /**
+ * @requires javelin-stratcom
+ * @provides duck
+ */
+
+ /**
+ * Put class documentation here, NOT in the header block.
+ */
+ JX.install('Duck', {
+ ...
+ });
+
+Then rebuild the Celerity map (see the next section).
+
+= Changing an Existing File =
+
+When you add, move or remove a file, or change the contents of existing JS or
+CSS file, you should rebuild the Celerity map:
+
+ phabricator/ $ ./scripts/celerity_mapper.php ./webroot
+
+If you've only changed file content things will generally work even if you
+don't, but they might start not working as well in the future if you skip this
+step.
+
+= Including a File =
+
+To include a CSS or JS file in a page, use
+@{function:require_celerity_resource}:
+
+ require_celerity_resource('duck-style-css');
+ require_celerity_resource('duck');
+
+If your map is up to date, the resource should now be included correctly when
+the page is rendered.
+
+You should place this call as close to the code which actually uses the resource
+as possible, i.e. **not** at the top of your Controller. The idea is that you
+should @{function:require_celerity_resource} a resource only if you are actually
+using it on a specific rendering of the page, not just because some views of the
+page might require it.
+

File Metadata

Mime Type
text/x-diff
Expires
Tue, Dec 2, 10:25 PM (3 h, 58 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
432879
Default Alt Text
(3 KB)

Event Timeline

styx copyright 2020 sirocyl / ellie (kymkdd) / ncommander / styx contributors
Use of other names and brands is not intended to reflect a claim of, or right to, use the name or brand.
styx is an operating system using the Linux kernel and components, and "styx Linux" as a phrase does not reflect the inclusion of the Linux brand or trademark in the styx project.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
Terms and Conditions (TODO: fix this!)