diff --git a/definitions-01.png b/definitions-01.png new file mode 100644 index 00000000..0f45607c Binary files /dev/null and b/definitions-01.png differ diff --git a/definitions.md b/definitions.md new file mode 100644 index 00000000..3a31eb76 --- /dev/null +++ b/definitions.md @@ -0,0 +1,109 @@ +# Site Definitions + +> This documentation is not required to effectively use *Try WordPress*. It is intended for users who would like to contribute to the development of the project, or would like to better understand how *Try WordPress* works internally. + +Site *Definitions* make it easier for you to import your site by allowing *Try WordPress* to automate parts of the import process. If your existing site is hosted on a *Platform* for which there is a *Definition* (for example, Ghost or Drupal), *Try WordPress* will automatically understand how your site is structured, and will be able to import content in a mostly-automated way. + +You are still able to import your site even if there currently is no *Definition* for the platform where your site is hosted. In this case, *Try WordPress* will guide you through creating a custom *Definition*, which is then used throughout the import process. You also have the option of contributing the *Definition* you created so that it's included in future versions of *Try WordPress*, if you think it could be useful to others. +## Source *Platforms* + +Before diving into what a *Definition* is, it's important to understand the notion of *Platform*. *Try WordPress* is able to import sites regardless of where they are hosted, or which technology they're built on. Examples of *Platforms* might be: + +- Ghost, Jekyll or other static site engines +- Drupal, Joomla, WordPress or other CMSes +- Cloud hosting platforms like Wix or Squarespace +- Generic web servers + +*Try WordPress* can import content from a *Platform* in two ways: + +1. **Structured import**: When the Platform provides an API, or an export feature that allows you to export your content as a zip file, for example. This type of import is mostly automated and produces the best results. **In this mode, a *Definition* is not needed** because *Try WordPress* will already be able to access the content in a structured form. +2. **Generic import**: When there is no way for *Try WordPress* to obtain the content of the source site in a structured form. In this mode, *Try WordPress* guides you through the process of creating a custom *Definition*, and then uses that *Definition* to extract the content from your site's HTML. +## What is a *Definition*? + +A *Definition* is in essence a text file that defines the structure of the content in your site. If your site consists of a blog section and several pages, it might look something like the following: + +```json +{ + "name": "My Website", + "subjects": { + "blogPost": { + "title": { + "type": "text", + "path": "//div[@id='title']" + }, + "date": { + "type": "date", + "path": "//div[@id='date']" + }, + "content": { + "type": "html", + "path": "//div[@id='content']" + } + }, + "page": { + "title": { + "type": "text", + "path": "//div[@id='date']" + }, + "content": { + "type": "html", + "path": "//div[@id='content']" + } + } + } +} +``` + +> The `path` fields in the example above are merely examples. In reality, the paths might be more complex, and will vary from website to website. +### Types of fields + +In the example above you can see that each field has a `type`. This is necessary for *Try WordPress* to correctly interpret the information. Currently, the following types are available: + +- `text`: Plain text, like the title of a Blog Post, or the name of a Product +- `date`: For example, the date a Blog Post was published, or the start time of an Event in a calendar. +- `html`: Any HTML markup. + +In the future, as *Try WordPress* develops, there will be other types of fields. + +## Creating a *Definition* + +*Try WordPress* provides a UI for creating *Definitions*, so you do not need to manually create the *Definition*'s text file. You select the fields through the UI and the *Definition*'s file will be created in the background. Here's an example of what the UI for selecting the title of a Blog Post looks like: + +![definitions-01.png](definitions-01.png) + +## Contributing a *Definition* + +TODO +UI + +## Other ways to contribute + +- Another way of contributing would be verifying definitions +- Fixing issues in definitions + + + + +---- + +- A new page for contributing, but not contributing to the code +- Manual of the tool for the user + - But also manual for how a non-technical user can contribute +- Take all this and write a “mission statement” +- How would contribution work? Avenues of contribution. +## UI + +- What would the finished extension look like? + - Mock screenshots for how a user can contribute +- How would this contribution flow work? + - Click a button to “share” definition +- A theme on Squarespace + - Suggest to use a prior definition that was created by a user for the same theme +- At the end of an import + - “Export” so that other users can take advantage of that work +## FTR + +- “Pre-processing” step + - FTR config as a “strip” step + - “We need to prepare the source site first” + - First remove stuff that is “in the way”