Idealogs:Documentation

Articles [edit]

A synesiary (e.g. Idealogs) is a wiki that catalogs subjects of interest, along with their relevant writings, statements, and questions (WSQs). This corresponds to four different types of articles in the wiki, each represented by its own unique domain:

Item Article Type Domain Content
subjects of interest Definite @0 A literature review of the most important WSQs that shape our understanding of the subject.
writings Transfinite @T A summary/analysis of the writing, using the special linking mechanism to make references to and inferences from the text.
statements Infinite @I An explanation of the statement and a summary/analysis of the proofs that substantiate it. All proofs must be sourced from primary sources already cataloged on the site as writings.
questions Finite @F A summary/analysis of the question. This article should layout all the relevant sides of the debate, explain where the sides agree and disagree, describe the question’s origin and evolution over time, and spell out any other information that helps put the question in context. In other words, this article should spell out the question’s Five Ws: “Who, What, When, Where, and, Why”. Our underlying mindset is to seek to define the question, not answer it.

See Idealogs:Types of Articles for a deeper discussion of the four types of articles and what goes in them.

Handles

Unlike in a traditional wiki, articles on this site are identified by a unique handle. Handles are composed of a domain and a range, and are formatted as [domain]x[range]. Ranges are encoded in hexadecimal (see ).

This article has the handle @0x66F7B7, which means it is in the ‘@0’ domain and thus refers to a subject. Some more examples:

Handle Domain Range Translation
@0x0 @0 0 a subject article
@TxA @T A a writing article
@IxEF3 @I EF3 a statement article
@FxB22A8 @F B22A8 a question article
@Enderx3 @Ender 3 an article published by the user @Ender outside of the wiki. See for more info.

Domains

Domains are a tool to quickly identify which type of article you are reading. There are four default domains, corresponding to the four types of articles in a synesiary. When you create an account, you are also assigned your own domain which corresponds to the Pen Name you chose. See works for more info.

Ranges

Ranges are automatically generated by the software when you create a new article. They are relevant only in that they allow you to uniquely refer to any article in a given domain. Ranges use the hexadecimal numeral system.

Titles

The title of an article is located at the top of the page. It identifies the item being cataloged in the fewest words possible.

The title of an article can be changed freely from edit to edit. This is because an article is uniquely identified by its handle, not its titlethis is in direct contrast to Wikipedia, where articles must be “moved” in order to change their title

. In practice, title edits must be properly justified or else they will be reverted.

Subtitles

The subtitle of an article, located directly beneath the title when visible, displays the article’s handle. If you are on the article’s “Read” page, the shortcut CMD+S will show or hide the subtitle.

Meta

You can easily view pertinent information about the commit you are viewing by clicking the handle of the article, located in the subtitle. For example, scroll to the top of this page and click the link for ‘@0x66F7B7’. The log will also provide a button for editing the article (if you have permission to do so), and also a button for viewing the changes made by this commit, among others.

If you are on the article’s “Meta” page, the shortcut CMD+M will show or hide the meta box.

URLs

The URL of an article is simply the article’s handle.

Commits

An article in a synesiary is the sum of a finite number of commits. A commit is roughly equivalent to an ‘edit’ in a wiki.

Suffixes

The four article types in a synesiary each have an associated suffix that is used for for and of that type.

Article Type Catalogs a Suffix
subject ;
writing ,
statement .
question ?

For example, to query the index for all finite articles (i.e. questions) concerning World War 2, you would input World War 2?.

If your query does not end in an appropriate suffix, then you will receive results from all four domains.

Pages [edit]

Every synesiary article is composed of two pages: an Article page, and a Talk page. This is identical in structure to a standard wiki, and the properties and functions of each are parallel to their wiki counterpart.

Transfinite articles have an additional page, called a . This is something unique to a synesiary and not found in other wikis.

Article page

Identical in function to the ArticleAlso known as a “Ken” page. Ken (n.) means understanding, as in beyond one’s ken. A Ken page is place for understanding.

page of a Wikipedia article.

Talk page

Identical in function to the Talk page of a Wikipedia article. Common syntax for editing a Talk page:

Syntax Explanation
[@user] Sends @user a notification that they’ve been mentioned in the edit.
~~~~ Inserts a user’s signature into the edit. Used to attribute a comment to its author.
> Text indent. Used to format edits in the form of a conversation.

Text page

All transfinite articles are associated with a writing which the article is meant to . If the writing was published as a or was published elsewhere on the web, then the “Text page” is simply a link to the writing itself; if, however, the writing is in the public domain or we have secured the rights to republish it, then it is a bona fide wiki page itself which can be edited like any other page in the synesiary.

In other words, there are three categories of writings based on where the writing was originally published:

Category Description Text page
Published elsewhere The most common case. The transfinite article creates a reference to the original publication. A link to the writing if one exists.
Published on this site A . See for more info. A link to the writing.
Published elsewhere, but republished here Either a writing in the public domain, or one which we secured the rights to republish. This type of transfinite article has a Text page which houses the republished writing, and which can be edited like any other article in the wiki. For an example, see []. An actual wiki page which can be edited like any other.

Creating New Articles [edit]

If I’m cataloging… Then I enter… Example Identifier Suffix
a subject identifier; Cheese; title ;
a writing identifier, https://www.example.com/mmmmm-cheese, URL/DOI/PMID/ISBN if possible; title otherwise ,
a statement identifier. Cheese is delicious. title .
a question identifier? Why is cheese so delicious? title ?

In the top left corner of the Idealogs home page, there is a link that says ‘new’. This takes you to the tool for creating new articles in the wiki. Alternatively, go to the sidebar and click the “New article” link in the “Contribute” section.

To create a new article:

  1. Enter the article’s identifier followed by its suffix to specify which domain the article belongs in. Hit ‘Enter’.
  2. Check the results below to ensure the article does not already exist on the site.
  3. Press ‘Submit’.

The article’s identifier and suffix depend on whether you are cataloging a subject, writing, statement, or question:

For example, the query What is the answer to life, the universe and everything? will generate the option to catalog ‘What is the answer to life, the universe and everything?’ as a question in the wiki.

Writings

If you are cataloging a piece of writing that has a unique identifier, use it in your query. Doing so will allow the software to automatically add relevant bibliographic metadata to the article. Examples of unique identifiers include

  • URL (ideally, a stable one)
  • DOI
  • arXiv ID
  • PMID
  • ISBN
Identifier Type Writing Query
DOI The academic paper “The spread of true and false news online” (2018) 10.1126/science.aap9559,
URL The article from the Washington Post that first reported the Saturday Night Massacre https://www.washingtonpost.com/politics/nixon-forces-firing-of-cox-richardson-ruckelshaus-quit-president-abolishes-prosecutors-office-fbi-seals-records/2012/06/04/gJQAFSR7IV_story.html,

Notice the comma at the end, which is the suffix for cataloging writings and not part of the identifier.

Editing [edit]

To reach an article’s editing interface, either click the ‘Edit’ link in the top right of the page, or click the ‘Edit’ button that is accessible via the article’s block.

Authenticated vs. Anonymous

The editing workflow of an article differs depending on whether you are signed in or not.

The latter is nearly identical to the editing workflow on Wikipedia: make your changes, write a short message which describes your changes, preview the changes you are about to make, and then commit them to the database.

The former provides more flexibility. You can

  • save uncommitted changes as you work;
  • click the ‘Changes’ button to highlight the changes you have made so far; and
  • quickly access all the articles you are actively working on from your ‘Workspace’, located in the upper right corner of the screen.

Markdown

Articles on this site are written in Markdown. If you are unfamiliar with Markdown, do not be afraid! It is easy to learn. I recommend googling ‘Markdown Tutorial’ and checking out the first few links. Another easy way to learn it is to simply click ‘Edit’ on some articles on this site to see how it works. This site uses Pandoc-flavored Markdown.

YAML Headers [edit]

Idealogs uses YAML header blocks for storing article metadata. A great way to learn more about YAML headers and how they work is to find transfinite articles on the site and look at their source.

Citation Style Language

The vast majority of the fields in a synesiary article YAML header are as specified by the Citation Style Language (CSL) format. See their spec [] for more details.

Synesiary YAML Specification

There are, however, a couple custom and/or modified fields which are specified below.

Field Example Required Usage Notes
title title: Hello World! yes All articles All articles must have a title
comments_on comments_on: Tx3 no transfinite, The article being commented on must be transfinite. Once this field is set, you can make to the writing you specified.
PDF PDF: https://tyfried.github.io/files/discourse.pdf no transfinite For use when the primary source is a PDF hosted somewhere on the web. Also used specifically in conjunction with .

References

In addition to the above, transfinite articles use the YAML header block to store bibliographic data about the writing in the Citation Style Language (CSL) format []. This metadata is then used to generate a reference for the writing using CiteProc []. To display a reference at the bottom of a writing article, ensure that the final line of the document is


The software will then autogenerate a reference using the metadata provided. Note: this line is added to the end of writing articles by default.

Linking [edit]

Linking to other articles in the synesiary is very easy. All you need is the article’s handle.

Markdown Syntax HTML Notes
[@TxA] [<a href="/@TxA">TxA</a>] NA
[???, ???] [<a href="/@TxA">TxA</a>, <a href="/@Ix6">Ix6</a>] NA
[<a href="/@0xAA17A6">Idealogs</a>] Only works for definite articles
\[\@0xAA17A6 | Hello World] [<a href="/@0xAA17A6">Hello World</a>] Only works for definite articles

Note that when you link to an article, the text of the link is simply the handle itself. This is not true for linking to definite articles, however. By default, the text of the link will be the title of the article, but you can change what text is displayed as in the example above. This only works for linking to a single definite article, though. In particular, something like [@0xZ | something else; \@IxZ; \@FxZ] would be invalid.

Also note that traditional markdown linking is in a synesiary.

Direct linking

Within articles and , there is a special syntax for making links directly to text fragments [] or other specific locations within the primary source that is being cataloged.

Markdown Syntax Example HTML Works for
[textDisplay | textSource] [Brown fox | the quick brown fox] <a href="https://www.example.com#:~:text=The%20quick%20brown%20fox">Brown fox</a> HTML
[textDisplay | textSourceStart | textSourceEnd] [Brown fox | The quick brown | lazy fox.] <a href="https://www.example.com#:~:text=The%20quick%20brown,lazy%20fox." >Brown fox</a> HTML
[textDisplay | #page=XXX] [Page 70 | #page=70] <a href="https://www.example.com/test.pdf#page=81" rel="noopener">Page 70</a> PDF
[textDisplay | #whatever-you-want-here] [Hello world | #hello-world] <a href="https://www.example.com/test.pdf#hello-world">Hello world</a> HTML

Note: this text fragment highlighting feature is only supported by Chromium based browsers (e.g. Chrome, Edge) at the moment.

Reciprocal Linking

A synesiary uses the metric to rank each article based on how many internal links it contains. In short, the more reciprocal links an article has, the higher its visibility is in , and vice versa.

Front page [edit]

The front page of Idealogs is a feed of articles ranked according to the metric. The feed is .

KenScore [edit]

Every article in the synesiary is ranked according to a custom metric called KenScore. It was inspired by and operates similar to Reddit’s original hot ranking algorithm [].

Basics

Every time an article links to another in the synesiary, one of the articles receives a score for that link, according to the following logic: the article with a lower number of receives a negative “link initiation” score at the time when the asymmetrical link is first created, while the article with a greater number receives a positive “link reciprocation” score at the time when the asymmetrical link is reciprocated and becomes symmetrical. If the articles have the same number of symmetrical links, then the more recently created article is considered to be article with less symmetrical links.

An article’s KenScore is the median value of all its link initiation and link reciprocation scores.

In theory, this

  • creates a live, up-to-date feed of the best writings, statements, and questions being discussed in the world right now, ie a veritable slice of what is “currently going on”;
  • increases exposure to ideas which are already well-established according to the number of reciprocated links they contain;
  • decreases exposure to newer ideas that have not yet gained traction;
  • and incentivizes authors who publish or writing elsewhere on the web to be creative and include new, original thought in their work if they want to have it receive exposure in the synesiary as a article. This is a direct result of the emphasis on : asymmetrical links are associated with , and when not reciprocated they either decrease or have no effect on the exposure of the articles involved.

Setup: givens, definitions

Let \(|X_t|_{sym}\) and \(|X_t|_{asym}\) be the number of symmetrical and asymmetrical links in article \(X\), respectively, at time \(t\).

Let \(\mathbb{L}_{X_t}\) be the set of articles which link to \(X\) or are linked to by \(X\).

Let articles \(A\) and \(B\) be two articles in the synesiary such that \(|A_t |_{sym} \leq |B_t |_{sym}\).

Let time \(U\) be the moment that an asymmetrical link \(L_{AB}\) was initiated between articles \(A\) and \(B\), and time \(V\) be the moment that the asymmetrical link \(L_{AB}\) was reciprocated by the other article, \(U < V\). It is irrelevant which article initiated the link and which reciprocated; article \(A\)–the one with fewer symmetrical links–will always receive the lower score and article \(B\) will always receive the higher score.

Let time \(W\) be September 9th, 2003 1:21:17 p.m. ET

Let \(s_{asym}\) be the difference in seconds \[s_{asym} = U - W,\] and \(s_{sym}\) be the difference in seconds \[s_{sym} = V - W.\]

Let \(x(t)\) be the average of the difference in asymmetrical and symmetrical link counts in \(A\) and \(B\) at time \(t\) \[x(t) = \text{avg}(|A_t|_{sym} - |A_t|_{asym}, |B_t|_{sym} - |B_t|_{asym})\] and \(y(t)\) be the maximal value of \(x(t)\) and 1 \[y(t) = \max(x(t),1).\]

KenScore

The KenScore for article \(A\) at time \(t\) is calculated as the median value of all of \(A\)’s link initiation and link reciprocation scores \[KS(A_t) = \text{med}( LS_{init}(A_t) \cup LS_{recip}(A_t))\] where \[LS_{init}(A_t) = \{ LS_{init}(L_{AX}) \ \text{for} \ X \in \mathbb{L}_{A_t} \}\] and \[LS_{recip}(A_t) = \{ LS_{init}(L_{XA}) \ \text{for} \ X \in \mathbb{L}_{A_t} \}.\]

Result

The result of the KenScore metric is a time-based feed of all the articles in the synesiary based on how often and recently each individual article has been linked to and the relative quality of all of its links. It is very similar to and inspired by Reddit’s original front page algorithm.

PageRank [edit]

Every article is also ranked according to the out-of-the-box PageRank algorithm. Every article is a node, and every inter-article link is a uni-directional edge in the graph. The PageRank metric is used to provide more accurate search results.

Searching [edit]

There are two ways to search for articles in Idealogs which provide two very different user experiences, depending on whether you include a in your query or not.

The default search method uses the metric. When you first land on the Idealogs home page, you will see all articles ranked according to this algorithm. Further, if you search for an article using the keyword search and do not include one of the four in your search, then the search result will simply filter out articles from this ranked list that don’t match the keywords you provided in your query.

The secondary search method uses the metric. If you do include a suffix in your query, then the search result will return articles ranked by relevance according to the keywords you provided and the article’s overall PageRank. In other words:

If your query… then your search result will use the … metric.
does not include a , KenScore
includes a , PageRank

Shortcuts [edit]

There are a number of shortcuts on Idealogs to quickly accomplish commonly performed tasks. Javascript must be enabled for these shortcuts to function properly.

Read Page

Shortcut Action Notes
CMD + M Show/hide article meta
CMD + S Show/hide article subtitle
CMD + D Toggle between the article and the underlying Only applies to transfinite articles associated with a writing published on this site

Edit Page

Shortcut Action Notes
CMD + S Save your current progress
CMD + E Show/hide a current preview of your edit
CMD + D Switch text direction from left-to-right (LTR) to right-to-left (RTL). Useful for editing text in a RTL language (e.g. Hebrew, Arabic)
CMD + M Moves the cursor to the “Message” input box Only if editing anonymously
s Moves the cursor to the search box

Changes/Stage Page

Shortcut Action Notes
CMD + SPACEBAR Jump to the next change
CMD + B Jump to the previous change
CMD + M Moves the cursor to the “Message” input box Only for Stage

List view

“List view” refers to any page on the site that is a list of objects.

Shortcut Action Notes
CMD + E clear the contents of the search box

Accounts [edit]

You can create an account on Idealogs, but doing so is not necessary. The benefits of an account are that you can save drafts, publish your own separate from the wiki, and contribute to the works of other users.

Home Page

Your account home page is accessible from the top right corner of the screen. Your home page shows a log of all your commits on the site, sorted by time.

Panel

Your account settings are located in your panel. The panel is accessible from your user home page when you are logged in. From your panel you can access your workspace, set your bio, turn hints on/off, see the articles you are watching, see the domains that you contribute to, etc.

Works [edit]

A work on Idealogs is a version controlled document that can be published on the site but outside of the wiki. Once a work is published, it can no longer be edited. If merited, however, the community can catalog the work as a in the synesiary so it can be integrated into the larger conversation and cited appropriatedly. A work has features similar to a project in a version control hosting servicee.g. GitHub, BitBucket

and a post in a blog.

Workspace

Starting from the ‘Workspace’ tab in the top right, press ‘new’. This will allow you to create an empty work.

Domains

By default, works are published under your default domain, the one that is associated with the account you created. You can also create new domains to publish under. All user-created domains must begin with “The”. Domain creation is accessible from the ‘Domains’ tab in the top right corner of the screen. It is not possible to change the domain of a work once it has been created.

Handles

Like articles in the wiki, all works have a handle that uniquely identifies it. A handle is composed in the same way: [domain]x[range], where ‘domain’ is the domain that the work is being published under.

Home Page

The work home page is the document itself, and is located at /@[domain]x[range].

Visibility

When creating a draft, you can choose its visibility.

Visibility Description
Private The work is hidden from the site until you publish it. Only you and people you explicitly choose can access the work until it is published.
Public The work is visible to all users. Any user can make a pull request for their changes to be committed to the work. Only you and contributors you explicitly choose can approve pull requests. Only you and contributors you explicitly choose can commit directly to the work.
Open The work is visible to all users. Any user can commit their changes without your approval. The difference between an open work and an article in the synesiary is that once the former is published, it can no longer be edited.

Contributors

You can add contributors to your domains to allow for collaboration among multiple users. This is most applicable when you have a private work that you want to give another user access to. To add a new contributor to your domain: from the domain home page, click the ‘contributors’ link, and then ‘new’.

Contributor Roles

As the owner of a work, you can assign roles to users who are contributors to that domain. This feature is accessible from the ‘Settings’ link on the work’s home page.

Role Applies To Description
Editor private, public, open Can edit the work. Can add/remove contributors. Can accept or deny pull requests for public works. Can publish a work (if there are two or more editors, publishing requires the approval of all of them.) Default role for user that created the work. Note: once an editor is added to a work, they cannot be removed.
Approver private Can approve a work for publication. Can edit the work. This role can only be assigned by the owner of the domain. This role only applies to private works published under non-default domains (domains that begins with ‘The’).
Writer private, public For private works, can read and commit. For public work, can commit.
Reader private Can read, but cannot commit.
Requester public This is role auto-assigned by the software to any user that makes a pull request to the work and doesn’t have a pre-defined role.
None public, open Use in the case where you need to block someone from contributing (e.g. in the case of vandalism)

Version Control System [edit]

Idealogs implements a simplified version control system for editing documents. The same system applies for works in your workspace and articles in the synesiary. This is necessary in order to support features like drafts, documents with multiple contributors, and pull requests. Every edit exists in one of the following states.

State Description
Saved A draft. Only visible to the user who created it.
Staged A draft that is about to be committed. Only visible to the user who created it.
Head The most recent commit.
Committed Any commit that was made prior to Head.
Requested A pull request.
Approved A Head commit of a work that has been approved for publication by an approver.
Published The Head commit of a work that has been published.
Submitted The Head commit of a work that has been published and then submitted for cataloging in the synesiary.
Rejected A pull request that has been rejected by the work’s editor. You can continue editing it as a draft by patching its changes into the current head commit of the article.
Readonly A saved edit of a work that has been published and thus can no longer be edited. These changes can only be discarded.
Idealogs Extension Icon