Quem mantém um arquivo de notas com links há mais de um ano já topou com este bug.
Você escreveu uma nota chamada Q3 planning. Em oito meses, trinta outras notas passaram a fazer referência a ela. Aí o terceiro trimestre acabou, e você a renomeou para Q3 planning (2025) — o óbvio a fazer.
Trinta links quebraram. Sem barulho. Continuam aparecendo, continuam parecendo links e agora apontam para uma nota que não existe. Alguns sistemas, prestativos, se oferecem para criá-la, e você acaba com uma segunda nota Q3 planning, vazia, assombrando o seu grafo.
A causa: a maioria dos apps de anotações no estilo wiki guarda o link como o título. [[Q3 planning]] é literalmente a string "Q3 planning", resolvida na hora de renderizar com uma busca por uma nota com esse nome. O link é um palpite que, na maior parte das vezes, acerta.
O Notez guarda o id.
O que o [[ insere de fato
Digite [[ no editor e abre-se um seletor com as notas do seu espaço de trabalho. Escolha uma — ou crie uma nota nova ali mesmo, no seletor — e o que entra no documento é um nó com duas informações:
noteId— o identificador real da nota de destinofallbackTitle— o título no momento em que você inseriu o link
O id é o link. O título de reserva é uma legenda para último caso.
Quando o chip é renderizado, ele busca a nota de destino pelo id e mostra o título atual. Renomeie a nota de destino e todos os chips que apontam para ela se atualizam, em todo lugar, na hora. Nada para consertar, nenhum localizar e substituir em massa no arquivo, nenhum relatório de "links não resolvidos" para revisar num domingo.
Isso também deixa os links sem ambiguidade, coisa que links por título nunca conseguem. Duas notas podem ter o mesmo título. Duas notas não podem ter o mesmo id.
Backlinks são uma consulta, não um recurso que você mantém
Como os links são guardados como referências reais, a direção inversa sai de graça.
Toda vez que uma nota é salva, o Notez percorre o documento salvo, coleta os ids das notas que ele referencia e compara esse conjunto com o que tinha registrado antes — insere os links novos e apaga os removidos. A tabela de links é uma função pura do seu conteúdo. Ela não tem como sair de sincronia com o que você escreveu, porque é reconstruída a partir do que você escreveu a cada salvamento.
Algumas coisas são filtradas nessa passada, cada uma por um motivo concreto:
Links para si mesma. Uma nota que faz referência a si mesma não é uma relação.
Destinos em outro espaço de trabalho. Só ficam as notas do mesmo espaço de trabalho. Por isso um link no espaço de trabalho do seu emprego nunca revela a existência de uma nota pessoal — não por regra, mas pela própria construção.
Ids malformados. Notas que vêm de uma importação podem trazer referências provisórias ainda não resolvidas, antes de a importação terminar de ligá-las. Essas referências são descartadas em vez de derrubar o salvamento.
Os backlinks são, então, a mesma tabela lida ao contrário: todas as notas cujo conteúdo faz referência a esta. Não existe um índice de backlinks separado para reconstruir nem modo de manutenção. A seção Notas vinculadas de uma nota mostra as duas direções.
Dois tipos de link, de propósito
Os links [[ no texto não são a única forma de uma nota apontar para outra. A outra é a propriedade personalizada do tipo Relação — um campo tipado na nota cujo valor é outra nota. Por exemplo, uma propriedade Client em cada nota de reunião, apontando para a nota daquele cliente.
Parecem iguais e são guardados de formas completamente diferentes. Os links no texto são gravados na tabela de links ao salvar. Os links de relação são derivados na leitura e nunca gravados lá.
O motivo é um bug que eu não quero pôr em produção uma segunda vez. A reconciliação ao salvar compara o conjunto inteiro de links de uma nota e apaga tudo o que não está no conteúdo. Se os links das propriedades de relação ficassem nessa mesma tabela, o próximo salvamento do conteúdo daquela nota olharia o documento, não os encontraria e os apagaria. Suas relações Client evaporariam uma nota de cada vez, exatamente no momento em que a nota fosse editada — ou seja, sem ninguém ver e só nas suas notas mais ativas.
Por isso os dois tipos ficam em armazenamentos separados e são unidos na leitura. Um pouco mais de trabalho a cada leitura; nenhuma chance de um engolir o outro em silêncio.
A diferença prática para você:
Links no texto são prosa. Cabem no meio da frase, onde a conexão é um pensamento que você está tendo: "isto decorre do [[postmortem dos retries]]".
Propriedades de relação são estrutura. Servem quando todas as notas de um tipo têm esse mesmo ponteiro e você quer filtrar e ordenar por ele.
Use os dois. Eles respondem a perguntas diferentes.
O grafo
Quando os links são referências reais, a visualização em grafo é só um jeito de desenhar dados que você já tem, e não uma coisa à parte para construir. A seção Notas vinculadas de qualquer nota pode ser vista como lista ou como grafo: com o que a nota se conecta e o que se conecta de volta a ela.
Uma ressalva: a visualização em grafo é útil de verdade para a exploração local — ver a vizinhança de uma nota, perceber um agrupamento que você não planejou. Para visualizar o arquivo inteiro, ela serve bem menos. Dez mil notas desenhadas como um novelo embolado são um protetor de tela. Eu fiz a local.
O que os links fazem numa nota compartilhada publicamente
Compartilhe uma nota publicamente e os links do texto se comportam com cuidado. A visualização pública não tem acesso ao seu espaço de trabalho, então o chip mostra o fallbackTitle capturado no momento da inserção — a legenda de último caso, enfim, cumprindo seu papel — e só vira um link que funciona se a nota de destino também estiver compartilhada publicamente.
Se não estiver, o chip aparece como texto inerte, em cinza. Ele avisa o leitor de que ali há uma referência, sem revelar o título atual da nota nem dar acesso a ela.
Esse é o padrão correto, e vale saber antes de compartilhar uma nota: uma nota compartilhada não arrasta as notas vinculadas para a visualização pública junto com ela. Se você quer que um conjunto de notas vinculadas possa ser lido, compartilhe cada nota dele.
Um jeito prático de usar isso
Links são um daqueles recursos fáceis de planejar demais e depois nunca usar. O que funciona de fato:
Crie o link enquanto escreve, não depois. O momento em que você digita uma frase que se refere a algo que já escreveu é o momento em que você sabe que o link existe. Depois, você não vai lembrar.
Não crie links para tudo. Uma nota com links vindos de quarenta lugares não diz nada. Links só são sinal quando são seletivos.
Confira os backlinks antes de escrever uma nota nova. Abra a nota sobre o assunto, veja o que já aponta para ela, e muitas vezes você vai descobrir que escreveu boa parte da nota nova oito meses atrás.
Transforme um link repetido numa propriedade de relação. Se você criou à mão um link para a nota de um cliente em cada nota de reunião, isso já não é prosa — é um campo. Transforme-o em campo e ganhe filtro e ordenação de graça.
Renomeie à vontade. É esse o ponto. Títulos são descrições, não identificadores, e você deve poder melhorá-los sempre que pensar num melhor.
Esse último é o benefício silencioso dos links por id, e leva um tempo para ser notado. Num sistema com links por título, você aos poucos para de renomear as coisas, porque renomear tem um custo e você já se queimou. Acaba com um arquivo cheio de títulos com os quais se conformou.
Com links que sobrevivem a uma renomeação, os títulos continuam melhorando.
Continue lendo
Por que o seu app de anotações não encontra a sua nota — como a busca por palavra-chave e a busca semântica funcionam lado a lado, e por que a busca e as Notas semelhantes usam limites de distância diferentes.
O responsável que não trabalha mais aqui — por que remover alguém de um espaço de trabalho limpa as atribuições dessa pessoa em vez de deixar um nome em cinza em quarenta notas.
Notez: um aplicativo de anotações feito para desenvolvedores — o que é o Notez, as formas de uma nota chegar até ele e o que cada plano inclui.