Skip to content
Permalink
Browse files

Initial design and content

  • Loading branch information
Gary Mann
Gary Mann committed Aug 17, 2019
1 parent 55622a0 commit 25ad2a9667c14156e5ac127f5c8100759e720687
Showing with 3,173 additions and 1 deletion.
  1. +5 −0 .gitignore
  2. +4 −0 Brewfile
  3. +20 −0 LICENSE
  4. +24 −0 Makefile
  5. +9 −1 README.md
  6. +5 −0 archetypes/default.md
  7. +16 −0 bin/merge-rules
  8. +37 −0 config.toml
  9. +3 −0 content/_index.md
  10. +9 −0 content/docs/_index.md
  11. +3 −0 content/docs/how-typedescriptor-links-source.md
  12. +3 −0 content/docs/listings/_index.md
  13. +18 −0 content/docs/listings/rules/_index.md
  14. +19 −0 content/docs/listings/rules/archived.md
  15. +25 −0 content/docs/listings/rules/assemblies-and-source-dont-match.md
  16. +19 −0 content/docs/listings/rules/code-not-updated-recently.md
  17. +21 −0 content/docs/listings/rules/default-package-description.md
  18. +27 −0 content/docs/listings/rules/not-enough-interest.md
  19. +36 −0 content/docs/listings/rules/url-must-not-be-default-or-example-configuration.md
  20. BIN static/favicon.ico
  21. BIN static/org_logo.png
  22. +1 −0 static/svg/calendar.svg
  23. +5 −0 static/svg/close.svg
  24. +1 −0 static/svg/edit.svg
  25. +4 −0 static/svg/menu.svg
  26. +1 −0 static/svg/org_logo.svg
  27. +9 −0 themes/neige/assets/css/buttons.css
  28. +139 −0 themes/neige/assets/css/content.css
  29. +22 −0 themes/neige/assets/css/dev/postcss.config.js
  30. +40 −0 themes/neige/assets/css/highlight.css
  31. +35 −0 themes/neige/assets/css/postcss.config.js
  32. +65 −0 themes/neige/assets/css/site.css
  33. +6 −0 themes/neige/assets/css/styles.css
  34. +20 −0 themes/neige/assets/css/tailwind.config.js
  35. +3 −0 themes/neige/layouts/404.html
  36. +25 −0 themes/neige/layouts/_default/baseof.html
  37. +8 −0 themes/neige/layouts/_default/list.html
  38. +6 −0 themes/neige/layouts/_default/single.html
  39. +36 −0 themes/neige/layouts/docs/baseof.html
  40. +12 −0 themes/neige/layouts/docs/list.html
  41. +18 −0 themes/neige/layouts/docs/single.html
  42. +3 −0 themes/neige/layouts/docs/single.json.json
  43. +5 −0 themes/neige/layouts/index.html
  44. +27 −0 themes/neige/layouts/partials/docs/git-footer.html
  45. +61 −0 themes/neige/layouts/partials/docs/menu-file-tree.html
  46. +3 −0 themes/neige/layouts/partials/docs/menu.html
  47. +7 −0 themes/neige/layouts/partials/docs/toc.html
  48. +16 −0 themes/neige/layouts/partials/footer.html
  49. +23 −0 themes/neige/layouts/partials/head.html
  50. +26 −0 themes/neige/layouts/partials/header.html
  51. +12 −0 themes/neige/layouts/partials/title.html
  52. +24 −0 themes/neige/package.json
  53. +12 −0 themes/neige/theme.toml
  54. +2,195 −0 themes/neige/yarn.lock
@@ -0,0 +1,5 @@
build
public

resources
node_modules
@@ -0,0 +1,4 @@
brew "hugo"

brew "node"
brew "nvm"
20 LICENSE
@@ -0,0 +1,20 @@
The MIT License (MIT)

Copyright (c) 2019 Typdescriptor

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,24 @@
.PHONY: build

BASE_URL="https://typedescriptor.org/"

browse:
( sleep 3; open http://localhost:1313 )&
make serve

serve:
hugo server --disableFastRender

prod/browse:
( sleep 3; open http://localhost:1313 )&
make prod/serve

prod/serve: prod/build
python3 -m http.server -d ./build

prod/build:
hugo -d ./build --minify --baseURL $(BASE_URL)
bin/merge-rules > ./build/json/docs/rules.json

init:
brew bundle
@@ -1,3 +1,11 @@
# Typedescriptor.org Website

This is the repository for the [Typedescriptor.org](https://typedescriptor.org) website
This is the repository for the [Typedescriptor.org](https://typedescriptor.org) website. This contains its [content](#content) and its [design](#design).


<a name="content"></a>
## Content


<a name="design"></a>
## Design
@@ -0,0 +1,5 @@
---
author:
title: {{ replace .Name "-" " " | title }}
date: {{ .Date }}
---
@@ -0,0 +1,16 @@
#!/usr/bin/env python3

import json
import glob
import re
from os import path

data = {}
for file in glob.glob('./build/json/**/index.json', recursive=True):
with open(file, 'r') as f:
name = path.basename(path.dirname(file))
name = re.sub('-(.)', lambda l: l[1].upper(), name)
name = name[0].upper() + name[1:]
data[name] = json.load(f)

print(json.dumps(data))
@@ -0,0 +1,37 @@
theme = "neige"

languageCode = "en-us"
title = "Typedescriptor.org"
pygmentsCodeFences = true
pygmentsUseClasses = true

[outputFormats]
[outputFormats.JSON]
isPlainText = true
path = "json"
mediaType = "application/json"
rel = "typedescriptor:data"

[params]

# (Optional, default docs) Specify section of content to render as menu
# You can also set value to '*' to render all sections to menu
BookSection = '*'

DateFormat = 'Jan 2, 2006'

# Set source repository location.
# Used for 'Last Modified' and 'Edit this page' links.
GitRepoURL = 'https://github.com/Typedescriptor/org-website'

# Path to GitHub edit page. Requires GitRepoURL to also be set
GitEditPath = 'blob/master/content'

# Whether to enable search box (Not fully implemented)
EnableSearch = false


[params.RuleTypeColorMap]
blocker = "red"
warning = "yellow"
informational = "blue"
@@ -0,0 +1,3 @@
---
title: 'Home'
---
@@ -0,0 +1,9 @@
---
title: 'Documentation'
---

This is the [_open source_](https://github.com/Typedescriptor/org-website) documentation for how Typedescriptor works.

## What's covered here

* [**Listing Rules**](/docs/rules) Articles that document how Typedescriptor finds problems in a listing proposed on [Typedescriptor Listings](https://typedescriptor.net/listings).
@@ -0,0 +1,3 @@
---
title: 'How Typedescriptor Links Source Code to Repositories'
---
@@ -0,0 +1,3 @@
---
title: 'Listings'
---
@@ -0,0 +1,18 @@
---
title: 'Listing Rules'
---

We strive to make Typedescriptor the best place to find and use high quality .NET software. We use Listings to do just that.


## Reasons why a package won't list on Typedescriptor

There are numerous reasons why a package or project won't list on Typedescriptor. This website provides a list of the problems that can occur and solutions for how to resolve them.

Problems are catgorized into three types: blockers, warnings, and informational warnings.

* **Blockers** are problems that must be resolved before the package can be listed on Typedescriptor. In somewhat rare cases, a moderator can override a blocker to allow a project to list on Typedescriptor.

* **Warnings** are problems that Typedescriptor recommends should be fixed, but which don't prevent listing a package. In the future, warnings could become blockers, so it is a good idea to address warnings anyway.

* **Informational warnings** are problems that Typedescriptor recommends should be fixed. These are usually problems that don't affect whether Typedescriptor can list a package or not.
@@ -0,0 +1,19 @@
---
title: 'Archived'
rule_type: blocker
outputs:
- html
- json
---

Project can't be archived.

Normally, owners archive projects when they are no longer interested in maintaining them.

## Why Typedescriptor checks for it

Typedescriptor doesn't list dead projects unless they are particularly vital to the .NET ecosystem. Archived projects are a very good sign that the project is dead.

## How to fix this problem

Reach out to a moderator if the project is an important .NET project. If not, then investigate whether the project can be unarchived or forked and re-released.
@@ -0,0 +1,25 @@
---
title: Assemblies and source code don't match
rule_type: blocker
outputs:
- html
- json
---

It looks like the code built into the assemblies is different than the source linked by the package (experimental).

> **Note** This rule is *experimental* and is known to generate false positives. Moderators can block this rule if it is causing false positives.
Typedescriptor compared the source code repository linked from the package to the metadata of the package assemblies, and there's too much of a difference to be sure that the source code repository linked in the NuGet package is the same as what was released.

## Why Typedescriptor checks for it

Typedescriptor checks for this to ensure that the package has source code and that the source code is really what is in the NuGet package. This is for security reasons and this is to ensure that Typedescriptor can actually navigate between metadata symbols and source code symbols.

## How to fix this problem

* **Read about how Typedescriptor [links source to repositories][1] and make any fixes**. It is possible that the URL Typedescriptor used is incorrect.

* Reach out to a moderator to conduct a manual review. This could take some time.

[1]: /docs/how-typedescriptor-links-source/
@@ -0,0 +1,19 @@
---
title: "Code Not Updated Recently"
rule_type: blocker
outputs:
- html
- json
---

It's been a while since code has been pushed to the repository.

Most projects need to have been updated once in the last two years. If a project is particularly mature, this could be a slightly longer interval.

## Why Typedescriptor checks for it

A project could be dead if it isn't updated regularly. Typedescriptor doesn't want to list projects that are dead unless they are particularly vital in the .NET ecosystem or particularly mature. Projects that aren't receiving code pushes are probably also not being supported or maintained actively.

## How to fix this problem

A maintainer needs to fix bugs, implement new features, or otherwise update the project, and this will resolve as it should.
@@ -0,0 +1,21 @@
---
title: Package description missing
rule_type: blocker
outputs:
- html
- json
---

The package doesn't have a useful description or it is missing.

## Why Typedescriptor checks for it

The package description is a high visibility field on Typedescriptor. Package maintainers are meant to set this field at least.

## How to fix this problem

* If you're creating the package manifest yourself or using the NuGet tools, check the value for the `description` field.

* If you're using MSBuild to generate the package via the [pack target][1], you should ensure that there is a value for `Description` being set in your project file.

[1]: https://docs.microsoft.com/en-us/nuget/reference/msbuild-targets#pack-target
@@ -0,0 +1,27 @@
---
title: "Not Enough Interest"
rule_type: blocker
outputs:
- html
- json
---

The project doesn't have enough stargazers, watchers, forks, or open active issues.

To list on Typedescriptor, a project has to meet some minimum thresholds in these areas, and they have to continue to be met and grow over time. These interest metrics curve with the project age. That is, when a project is relatively new or relatively old, these interest metrics don't have to change as much, which matches the expectation of a typical adoption curve.

## Why Typedescriptor checks for it

In order to find the best projects in the .NET ecosystem, Typedescriptor looks for signs of project popularity. There are several measures which matter in determining how popular a project is:

1. GitHub stargazers,
2. watchers/subscribers,
3. forks,
4. active issues and pull requests, and
5. other market and website information

## How to fix this problem

This problem is not easy to fix immediately. Even though this problem is usually a blocker, moderators can override it.

Gain popularity by promoting the project on blogs or on Typedescriptor!
@@ -0,0 +1,36 @@
---
title: 'URL must not be default or example configuration'
rule_type: blocker
outputs:
- html
- json
---

One or more URLs in the package manifest look like they were provided by default or by example.

To list on Typedescriptor, package maintainers must use real URLs for their project, license, and icon. When this error occurs, it looks like one or more of these have values that look like defaults or examples.

This error could be generated by package configuration similar to this:

```xml
<!-- Don't do this: the URL contains an example value -->
<licenseUrl> https://example.com </licenseUrl>
```

Notice the use of an example domain name.

## Why Typedescriptor checks for it

Some templates in tools like Visual Studio will generate NuGet package configuration that contains example or default values. Package maintainers are meant to update this to their own values before publishing their packages. If a package maintainer hasn't done this, it could be a sign that the package is low quality or doesn't have a professional web site yet.

## How to fix this problem

* **Use real values and real website addresses.** The simplest thing to do is to set these values. It's common to set them to your GitHub repository home page or GitHub Pages generated site.

* Avoid host names like `example.com` or any other reserved names.

* If you're creating the package manifest yourself or using the NuGet tools, check that the values for `licenseUrl`, `projectUrl`, and `iconUrl` are realistic.

* If you're using MSBuild to generate the package via the [pack target][1], you should investigate the values being used for `PackageLicenseUrl`, `PackageProjectUrl`, and `PackageIconUrl`.

[1]: https://docs.microsoft.com/en-us/nuget/reference/msbuild-targets#pack-target
BIN +29 KB static/favicon.ico
Binary file not shown.
BIN +847 Bytes static/org_logo.png
Binary file not shown.
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M20 3h-1V1h-2v2H7V1H5v2H4c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h16c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm0 18H4V8h16v13z"/><path fill="none" d="M0 0h24v24H0z"/></svg>
@@ -0,0 +1,5 @@
<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg">
<title>Close</title>
<polygon points="11 9 22 9 22 11 11 11 11 22 9 22 9 11 -2 11 -2 9 9 9 9 -2 11 -2"
transform="rotate(45 10 10)" />
</svg>
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M3 17.25V21h3.75L17.81 9.94l-3.75-3.75L3 17.25zM20.71 7.04c.39-.39.39-1.02 0-1.41l-2.34-2.34c-.39-.39-1.02-.39-1.41 0l-1.83 1.83 3.75 3.75 1.83-1.83z"/><path d="M0 0h24v24H0z" fill="none"/></svg>
@@ -0,0 +1,4 @@
<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg">
<title>Menu</title>
<path d="M0 3h20v2H0V3zm0 6h20v2H0V9zm0 6h20v2H0v-2z" />
</svg>
@@ -0,0 +1 @@
<svg viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg" fill-rule="evenodd" clip-rule="evenodd" stroke-linejoin="round" stroke-miterlimit="1.414"><path d="M202 20v216H54V20h148zm-30 43H83.773v129H172V63z" fill="#ffb340"/></svg>
@@ -0,0 +1,9 @@
.btn {
@apply bg-transparent border font-semibold px-4 py-2 rounded
}
.btn-blue {
@apply border-blue-500 text-blue-700;
}
.btn-blue:hover {
@apply bg-blue-500 border-transparent text-white;
}

0 comments on commit 25ad2a9

Please sign in to comment.
You can’t perform that action at this time.